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About This Book 



This information is avaiiabie in PDF and BookManager formats, and also as part of 
the information Management Software for z/OS® Solutions information Center . To 
view the information within the information Management Software for z/OS 
Solutions information Center , go to 

http://pubiib.bouiderJbm.com/infocenter/dzicheip/v2r2/index.jsp. To get the most 
current versions of the PDF and BookManager® formats, go to the iMS™ Library 
page at www.ibm.com/software/data/ims/library.html. 

This book is for IMS system and Transaction Manager administrators responsibie 
for installation, design, customization, operation, and recovery procedures for Open 
Transaction Manager Access (OTMA) servers or clients. It provides reference 
information for IMS system definition, customization, application programming, data 
communication and system administration for OTMA, It also provides information on 
writing an OTMA client. 

IMS Version 9 provides an integrated IMS Connect function, which offers a 
functional replacement for the IMS Connect tool (program number 5655-K52). In 
this information, the term IMS Connect refers to the integrated IMS Connect 
function that is part of IMS Version 9, unless otherwise indicated. 



How This Book Is Organized 

This book introduces OTMA, describes OTMA clients, discusses changes to IMS to 
support OTMA, and gives an overview of XCF for OTMA. This book contains the 
following chapters: 

• Chapter 1 , "Introduction to OTMA," on page 1 introduces the OTMA environment. 

• Chapter 2, "The OTMA Client," on page 13 describes what an OTMA client is. 

• Chapter 3, "Using IMS with OTMA," on page 39 describes how IMS tasks change 
when using OTMA. 

• Chapter 4, "OTMA Diagnostic information," on page 65 describes OTMA sense 
codes returned with negative acknowledgement messages. 

• Chapter 5, "OTMA Message Prefix," on page 71 contains the format of the OTMA 
message prefix. 

• Chapter 6, "OTMA Architected Transaction Attributes," on page 97 contains the 
syntax of architected command output. 

• Chapter 7, "OTMA Callable Interface," on page 101 , which was an appendix in 
previous releases. 

• "Bibliography" on page 159 contains a list of related publications (other than 
those in the IMS library). 



Prerequisite Knowledge 

IBM® offers a wide variety of classroom and self-study courses to help you learn 
IMS. For a complete list, see the IMS Web site at: www.ibm.com/ims. 

Before using this book, you should understand: 
« Basic IMS concepts 

• z/OS XCF programming 

• The IMS environment 
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• Your installation's IMS system 

• Your installation's networks 

• Administration of the IMS system and Transaction Manager 

For definitions of terminology used in this manual and references to related 
information in other manuals, see the IMS Version 9: Master Index and Glossary, 

IBM Product Names Used In This loformatioo 



In this information, the licensed programs shown in Table 1 are referred to by their 
short names. 

Table 1. Licensed Program Full Names and Short Names 



I iC£>rv>£>« program f-s\\ nan« 


Licensed program short name 


IBM Application Recovery Tool for iMs> and 


Application Recover/ Tool 






IBM Ck 1 fa section Server for < >S 390® 


CICS 


IBM CICS Transaction Server for z/OS 


CICS 


IBM DB2 Universal Database 1 '" 


DB2 Universal Database 


IBM DB2 Universal Database for z/OS 


DB2 UDB for z/OS 


IBM Enterprise COBOL for z/OS and OS/ 90 


Enterprise COBOL 


IBM E ntei prise PI i "o ? 0^ and l S 390 


p * PI 1 


IBM High Level Assembler for MVS""' & Vf ' & 
VSE 


High Lever Assemoler 


IBM IMS Advanced ACB Generator 


IMS Advanced ACB Generator 


IBM IMS Batch Backout Manager- 


MS Bit; Dat Soul '1a age 


IBM IMS Batch Terminal Simulator 


IMS Batch Terminal Simulator 


IBM IMS Buffe: Poo: Analyzer 


hvIS Bufstr Pool Anasi/zer 


IBM IMS Ccr na i Control -anlity o _ uS 


IMS Command Control t-acility 


H / Zyi^l'y /(.>> 


IMS Connect 


IBM IMS Connector for Java " 


IMS Connector for Java 


IBM IMS D^bd.e Cjniml S.itc 


MS VAxba c C>nl 3l °u c 


IBM IMS Database P.ecoverv Facility for z Ob 


IMS Database Recovery Facility 


IBM IMS Database Repair Facility 


IMS Database Reoair Facility 


IBM IMS DataPropagator " for z/uS 


IMS DataPropaqator 


IBM IMS DEDB Fast Recovery 


IMS DEDB Fast Recovery- 


IBM IMS Extended Terminal Option Support 


IMS ETO Support 


IBM IMS \ ar ^ath ^an; foot 


IMS Fast Path Basic Tools 


IBM IMS Fast Path Online Tools 


IMS Fast Path Online Tools 


IBM IMS Hardware Data 


IMS Hardware Data Compression-Extended 


Compression-Extended 




IBM IMS High Availability Large Database 


IBM IMS HALDB Conversion Aid 


(HALDB) Conversion Aid for z/OS 




IBM IMS High Performance Change 


IMS High Performance Change Accumulation 


Accumulation Utility for z/OS 


Utility 


IBM IMS High Performance Load for z/OS 


IMS HP Load 
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Table 1. Licensed Program Fuii Names and Short Names (continued) 



Licensed program fuH name 




Licensed program shert name 


IBM IMS High Performance Pointe 
for OS/390 " 


r Checker 


IMS HP Pointer Cnecker 


IBM IMS High Performance Prefix 
for z/OS 


Resolution 


IMS HP Prefix Resolution 


IBM z/OS Language Environment 




Language Environment 


IBM Tivoli® NetView® for z/OS 




Tivoli NetView for z/OS 


IBM WebSphere® Application Serv 
and OS/390 


er for z/OS 


WebSphere Application Server for z/OS 


IBM WebSphere MQ for z/OS 




WebSphere MQ 


IBM WebSphere Studio Application 
Integration Edition 


i Developer 


WebSphere Studio 


IBM z/OS 




z'OS 


IBM z/OS C/C++ C/C++ 



How to Send Your Comments 

Your feedback is important in helping us provide the most accurate and highest 
quality information, if you have any comments about this or any other IMS 
information, you can take one of the following actions: 

• Go to the IMS Library page at wwwJbm.corn/software/data/ims/library.htrni and 
click the Library Feedback link, where you can enter and submit comments. 

• Send your comments by e-mail to imspubs@us.ibm.com. Be sure to include the 
title, the part number of the title, the version of IMS, and, if applicable, the 
specific location of the text on which you are commenting (for example, a page 
number in the PDF or a heading in the Information Center). 
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Summary of Changes 



Changes to the Current Edition of This Book for MS Version 9 

This edition, which is available in softcopy format only, includes technical and 
editorial changes. 

The following technical and organizational changes have been made to this 
information: 

• ENQ/DEQ counts on a TPIPE are updated only for com mit-t hen-send output 
messages. This information is in "Modified Commands for OTMA" on page 60. 

• Added a new Rerouted Message flag in "Format of OTMA State Data for 
Transaction- Related Information" on page 82 under the content column titled 
Server State. 

« The Message in the Special Queue flag listed under the Processing Flag is not 
available for Shared Queues. This information is in "Format of OTMA 
Message-Control Information" on page 71. 

• Added the X'03' reason code to the 001 A sense code explaining that an incorrect 
input userid made the RACF RACROUTE VERIFY call fail. This information is in 
Table 12 on page 67. 

• Removed the reference of OTMA not supporting the /EXIT command from "IMS 
Conversations and OTMA" on page 45. 

• Updated the first paragraph of "OTMA Send-Then-Commit Messages" on page 
49 to explain the location for processing messages and transactions. 

• Added a new description for the Set Aging Value in the Client Flags section. This 
information is in "Explanation of OTMA State Data Fields" on page 88. 

• Added a new section, "DFSYIOE0 Input/Output Edit Exit" on page 42, to explain 
the OTMA DFSYIOE0 user exit. 

• Added a new section, "Tpipe Clean-Up" on page 52, to explain why OTMA 
removes Tpipes. 



Changes to This Book for IMS Version 9 

This edition contains the following changes: 

• Information related to the OTMA ACEE aging value setting, which is described in 
Table 14 on page 71 and "Explanation of OTMA Message-Control Information 
Fields" on page 75. 

• The section "OTMA Program-to-Program Switch Processing" on page 56, 
formerly titled IMS Program-to-Program Switch Processing, has been significantly 
rewritten. 

• The section "OTMA C/l Hints and Tips" on page 104 provides new information for 
using GTMA's callable interface. 

• Added new Auto-One option to Table 22 on page 87. 

• Description of Orse Only option is changed in Table 22 on page 87. 

• Added client flag to Table 15 on page 82, 

• Added explanation of Send Only Message and Reroute Request to "Explanation 
of OTMA State Data Fields" on page 88. 

• Added new section "Protecting Transactions with OTMA" on page 27. 
« New Purge Mot Deliverabfe flag added to Table 16 on page 84. 
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• Information formerly in the section, Frequently Asked Questions, has been moved 
to appropriate places in the book. Frequently Asked Questions has been 
removed. 



Library Changes for IfVfS Version 9 

Changes to the IMS Library for IMS Version 9 include the addition of one title, a 
change of one title, organizational changes, and a major terminology change. 
Changes are indicated by a vertical bar (I) to the left of the changed text. 

The IMS Version 9 information is now available in the information Management 
Software for z/QS Solutions Information Center , which is available at 
http://publib.boulder.ibm.com/infocenter/dzichelp/v2r2/index.jsp. The information 
Management Software for z/OS Solutions information Center provides a graphical 
user interface for centralized access to the product information for IMS, IMS Tools, 
DB2 Universal Database (UDB) for z/OS, DB2 Tools, and DB2 Query/ Management 
Facility (QMF™). 

New and Revised Titles 

The following list details the major changes to the IMS Version 9 library/: 

• IMS Version 9: IMS Connect Guide and Reference 

The library includes new information: IMS Version 9: IMS Connect Guide and 
Reference. This information is available in softcopy format only, as part of the 
Information Management Software for z/OS Solutions information Center , and in 
PDF and BookManager formats. 

IMS Version 9 provides an integrated IMS Connect function, which offers a 
functional replacement for the IMS Connect tool (program number 5655-K52). in 
this information, the term IMS Connect refers to the integrated IMS Connect 
function that is part of IMS Version 9, unless otherwise indicated. 

• The information formerly titled IMS Version 8: IMS Java User's Guide is now 
titled IMS Version 9: IMS Java Guide and Reference. This information is 
available in softcopy format only, as part of the information Management 
Software for z/OS Solutions information Center , and in PDF and BookManager 
formats, 

• To complement the IMS Version 9 library, a new book, An Introduction to IMS by 
Dean H. Meltz, Rick Long, Mark Harrington, Robert Hain, and Geoff Nicholls 
(ISBN # 0-13-185671-5), is available from IBM Press. Go to the IMS Web site at 
www.ibm.com/ims for details. 

Organizational Changes 

Organization changes to the IMS Version 9 library include changes to: 

• IMS Version 9: Customization Guide 

• IMS Version 9: IMS Java Guide and Reference 

• IMS Version 9: Messages and Codes, Volume 1 

• IMS Version 9: Utilities Reference: System 

I A new appendix has been added to the IMS Version 9: Customization Guide that 

I describes the contents of the ADFSSMPL (also known as SDFSSMPL) data set. 

The chapter titled "DLIModel Utility" has moved from IMS Version 9: IMS Java 
Guide and Reference to IMS Version 9: Utilities Reference: System. 
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The DLIMode! utility messages that were in IMS Version 9: IMS Java Guide and 
Reference have moved to IMS Version 9: Messages and Codes, Volume 1. 

Terminology Changes 

IMS Version 9 introduces new terminology for IMS commands: 
type-1 command 

A command, generally preceded by a leading slash character, that can be 
entered from any valid IMS command source. In IMS Version 8, these 
commands were called classic commands. 

type-2 command 

A command that is entered only through the OM API, Type-2 commands 
are more flexible than type-2 commands and can have a broader scope. In 
IMS Version 8, these commands were called IMSpiex commands or 
enhanced commands. 

Accessibility Enhancements 

Accessibility features help users who have physical disabilities, such as restricted 
mobility or limited vision, to use software products. The major accessibility features 
in z/OS products, including IMS, enable users to: 

• Use assistive technologies such as screen readers and screen magnifier 
software 

• Operate specific or equivalent features using only the keyboard 

• Customize display attributes such as color, contrast, and font size 

User Assistive Technologies 

Assistive technology products, such as screen readers, work in conjunction with the 
IMS user interfaces. For information about how to use assistive technology to 
access these IMS user interfaces, consult the documentation of the assistive 
technology product. 

Accessible Information 

The IMS Version 9 product information is available online in the following accessible 
formats: 

• HTML, in which you can access the IMS Version 9 library. You can find the IMS 
Version 9 library in the Information Management Software for z/OS Solutions 
Information Center at 

http://pubiib.boulder.ibm.com/infocenter/dzichelp/v2r2/index.jsp. 

• ISPF help panels, in which you can access the online help for the IMS Version 9 
ISPF applications. 

You can use screen readers and other assistive technologies to access the IMS 
Version 9 product information. 

Keyboard Navigation of the User Interface 

You can access the information center and IMS ISPF panel functions by using a 
keyboard or keyboard shortcut keys. 

You can find information about navigating the information center using a keyboard 
in the information center home at 

http://publib.boulder.ibm.com/infocenter/dzicheip/v2r2/index.jsp. 

For information about navigating the IMS ISPF panels using TSO/E or ISPF, refer to 
the z/OS V1R1.0 TSO/E Primer, the z/OS V1R5.0 TSO/E User's Guide, and the 



Summary of Changes XVII 



Z/'OS V1R5.0 iSPF User's Guide, Volume 1. These guides describe how to navigate 
each interface, including the use of keyboard shortcuts or function keys (PF keys). 
Each guide includes the default settings for the PF keys and explains how to modify 
their functions. 
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Chapter 1. Introduction to GTIVIA 



IMS Open Transaction Manager Access (OTMA) is a transaction-based, 
connectionless ciient/server protocol. Though easily generalized, its implementation 
is specific to IMS in a z/OS sysplex environment. The domain of the protocol is 
restricted to the domain of the z/OS Cross-System Coupling Facility (XCF). 

OTMA addresses the problem of connecting a client to a server so that the client 
can support a large network, or a large number of sessions, while maintaining high 
performance. 

Other solutions available today use network-based protocols, such as Systems 
Network Architecture (SNA). These protocols require a great amount of overhead 
because they are not transaction based. 

The following topics provide additional information: 
« "What is OTMA?" 

• "How IMS Messages Flow in an OTMA Environment" on page 5 

• "Using Transaction Pipes with OTMA" on page 8 



What Is OTMA? 



OTMA has similarities to network protocols. There are several architectural models 
for networks. Figure 1 shows two. The simplified four-layer model shown on the 
right is often used in descriptions of UNIX® networks. In the open systems 
interconnection (OS!) model, shown on the left, OTMA is the session layer. Both 
models have a Transport, Network, and Data Link layer. The OSI model also 
includes layers for Application, Presentation, and Session, and the simplified model 
includes a process layer. In the four-layer model, OTMA is the process layer. 



OSS Moee 
Application 
Premutation 
Session 
Transport 
Nerwo-k 
Data Lin* 
Pr-vs ca! 



Netwoi 



Mode'* 



Ol MA however does not exactly corlo'm to the OSi model, because OTMA can 
pro. es<- sevenl sessions simn raneously using a single transport connection, if the 
following are true: 

• The z/OS Cross-System Coupling Facility {XCF} is the transport layer. 
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What Is OTSVfA? 



• A session is the connection between IMS and a client. 

• A client or server only creates a single XCF connection, 

OTMA performs some of the basic functions of the OSI transport layer (those not 
performed by XCF), so it is simplest to think of OTMA as a combined session and 
transport layer, with the transport layer comprised of both XCF and OTMA. 

Although you can think of OTMA as a session and transport layer in a network 
architecture model, OTMA is designed to be a high-performance comprehensive 
protocol that allows z/OS programs to access IMS applications. 

Definitions: A z/OS program in this case means any z/OS application that is a 
member of an XCF group that includes IMS. The XCF group members that IMS 
communicates with are called OTMA clients. 

Related Reading: For more information on OTMA clients, see Chapter 2, "The 
OTMA Client," on page 13. 

By using OTMA, each client (z/OS application) can submit transactions to IMS or 
issue IMS commands and receive output from IMS application programs and from 
IMS itself. 

Definition: Because IMS can communicate with, or serve, many OTMA clients, 
IMS is called the server. However, OTMA only operates in the following IMS 
environments: 

• IMS TM and DB (the IMS DB/DC environment) 

• IMS TM with DB2™ UDB for z/OS (the IMS DCCTL environment) 

Capabilities of OTMA 

This section outlines the capabilities of OTMA 

Existing IMS application programs can run without modification and interact with 
OTMA clients. APPC/IMS application programs that use IMS SETO calls might need 
some modification. ReSated Reading: For more information on this restriction, see 
"OTMA Restrictions" on page 50. 

An OTMA client can issue most IMS commands and receive responses as a result 
of those commands. Reiated Reading: For information on the IMS commands that 
are supported, see the IMS Version 9: Command Reference. 

An OTMA client can indicate that no security checking is to be done for its 
messages, thereby minimizing security-processing overhead. 

The OTMA message flow and synchronization point protocols can be modified by 
an OTMA client for each transaction, in other words, the transaction-processing 
protocol used is not dependent on the current session. 

The IMS /DISPLAY TRANSACTION command output is in the form of an OTMA 
message returned to the client in the application-data section of the message prefix. 

OTMA-initiated transactions are identified to z/OS Workload Manager using the 
OTMA transaction-pipe name, which identifies the logical connection between IMS 
and OTMA. 
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Benefits of Using OTMA 

This section outlines the benefits of OTMA. 
Q: Do I need to modify my IMS applications? 

A: No, but if you have applications that use SETQ calls, you might have to modify 
them. The SETO call is relatively new and applies to APPC/IMS and SPOOL/API 
processing. 

For each OTMA-originated transaction, the SETO call returns a status code. You can 
bracket the SETO call with an INQY call if necessary; see "Using DL/i Calls in an 
OTMA Environment" on page 55. 

Full-duplex processing provides an environment in which transactions and output 
messages are sent and processed in parallel. 

You can implement IMS device support outside IMS. You can also implement device 
support for your IMS subsystem that is different from what IMS provides, or enable 
device support that IMS does not provide. Figure 2 illustrates how IMS can 
communicate with a device, shown here as a workstation, using device support 
implemented within an OTMA client. IMS device support using Virtual 
Telecommunications Access Method (VTAM®) is shown for comparison. 



IMS Subsystem 
-■ OTMA 



Devise 
S:;j:-pj:rt 



XCF | ! VTAM 



Devloe 

■* S-;J:pC:rt 




Device 



Figure 2. IMS communicates with a device using device support implemented within an 
OTMA Client 

Flow-control and transaction-processing attributes are dynamically bound to the 
transaction. 
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Clients have high-performance access to IMS: 

• OTMA uses the z/OS XCF application programming interface (APi). 

• OTMA does not use VTAM and IMS device-dependent support. 

Transactions based on different protocols (that is, thai have different processing 
requirements such as being recoverable or irrecoverable) can be associated with a 
single transaction pipe. Related Reading: For [more information on using 
transaction pipes, see "Using Transaction Pipes with OTMA" on page 8. 

You can connect up to 255 clients to the OTMA group. 

Messages can be extended using the user-data section of the message prefix, 
allowing additional user information to be sent with the transaction. 

User information and transaction pipe name are included within the messages 
themselves. 

Different clients can specify the same transaction pipe names, instead of needing to 
use uniquely named resources. 

You do not need to use networking architectures, such as SNA (Systems Network 
Architecture). 

Advantages of the OTMA Protocol 

OTMA treats transactions as data objects that have attributes independent of 
application-, session-, or transport-layer considerations. OTMA is, in effect, a 
transaction layer, independent of other layers. As a unique layer, OTMA offers 
flexibility, simplicity, and performance that other solutions do not offer. This section 
outlines the transaction-specific services that OTMA provides the client. 

Grouping of transactions using transaction pipes. 

Security options (for example, the client can verify security or let the server verify 
the user ID). 

Dynamically-bound flow control and processing. The client can decide how 
transaction requests and responses are to be processed by the server. 

The ability for the client to query the server for transactions that the server 
supports. 

Treating transactions as objects. The client can include any pertinent user data with 
the transaction, and allow that data to stay with ail messages generated by the 
transaction. 

The ability for the client to specify a client token with each transaction to correlate 
input with output. 

The ability for the client to control transaction processing performed by the server, 
in terms of: 

• Performance (the client can eliminate security-checking that the server performs). 

• Transaction grouping, using the transaction-pipe token. 
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Client routing. An iMS exit routine can reroute an output message that is inserted to 
an alternate PCB to any OTMA client or to IMS. 

Architected command output. The client can use the IMS /DISPLAY TRANSACTION 
command to query the server's transaction attributes and receive the reply in a 
structured format. Therefore, the need for automated operator scripting to control 
processing is reduced. 

Unlike APPC, when using message flow through transaction pipes, no concept 
exists of a session that contains the flow-control parameters for all transactions and 
associated output data for the session. 



How IMS Messages Flow in an OTMA Environment 

Definition: The key to message flow for OTMA is the transaction pipe, the logical 
connection between the server and the OTMA client. An OTMA client includes the 
transaction-pipe name in the message control information section of the message 
prefix for the input message. IMS then associates application output for an OTMA 
client with a specific transaction pipe. 

Related Reading: For more information on transaction pipes, see "Using 
Transaction Pipes with OTMA" on page 8. 

Basic OTMA Message Flow 

The basic message flow is: 

1 . The client submits a transaction or command to IMS. 

2. IMS accepts IMS transactions as input from any client. 

The IMS transaction code is specified in the application-data section of the input 
message. 

If the client is submitting an IMS command, the command is included in the 
application-data section of the input message. 

3. The input message is processed. 

An IMS transaction is enqueued to the appropriate application program using an 
IMS scheduler message block (SMB). 

An IMS command is processed by IMS. The output is sent to the client 
synchronously or asynchronously, depending on the type of request. 

4. Application output is sent to the client. 

Generation of output and commit are coordinated based on the commit mode 
specified in the state-data section of the message prefix for the input message. 
The application output is enqueued to a dynamically created IMS 
transaction-pipe structure (specific to that client) before being sent to the client. 
For an OTMA-submitted transaction, IOPCB output is returned to the OTMA 
client. By default, all alternate PCB output is also sent to the OTMA client. You 
can change this by coding the OTMA Prerouting exit routine (DFSYPRXO) or the 
client's OTMA Destination Resolution exit routine (DFSYDRUO). You can also 
use these exit routines to route alternate PCB output from non-OTMA-submitted 
transactions to OTMA clients. 

IMS delivers segmented messages in order, even though XCF does not 
guarantee sequential delivery of messages. 

Figure 3 on page 6 shows an example of the message flow in an OTMA 
environment. Two clients are shown side by side in the example; they can be a 
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TCP/IP client, an WebSphere MQ Queue Manager client, or a client of any other 
network type. Message flow starts with the client, goes through the XCF group, and 
to IMS. Within the IMS address space, a control region contains OTMA; the 
message flow ends at a transaction-pipe. The IMS application program issues a Get 
Unique (GU) call in the dependent region. 



Figure 3. IMS Message Flow in an OTMA Environment 
The notes in Figure 3 are as follows: 

1 . The message prefix is always attached to the input transaction, even in the 
case of segmented input. This prefix contains important information, such as the 
transaction-pipe name and the client token. 

A client application program can send several transactions specifying the same 
transaction-pipe name. The client token must always be present in the prefix, so 
that the client application program knows how to process the IMS output it 
receives. 

2. OTMA clients do not need to predefine transaction pipes. Two different clients 
can use the same transaction-pipe name (as shown in Figure 3). Although many 
clients can use the same transaction-pipe name, each transaction pipe is 
unique, (in Figures, client 1 and client 2 both use tpipel, yet each is a 
unique transaction pipe.) 

A client can create and use as many transaction pipes as it needs. 

3. The transaction-pipe structure is created dynamically when OTMA receives 
output and is used as an anchor for the application output. 
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4. The IMS application program has no knowledge of the OTMA message prefix 
when it issues the GU call. 

IMS supports a full-duplex message flow for a client/server session. The client can 
instead request a half-duplex message flow, but this flow must be implemented and 
managed by the client itself: 

• A correlator token in the state-data section of the message prefix can be used to 
uniquely identify a transaction. IMS maintains this field in the message prefix for 
a transaction. 

• The client can set the response-requested flag in the message-control 
information section of the message prefix to receive a response for a message. 

• Any unsolicited output from IMS is easily identified by a client, because the 
message prefix specifies only the transaction-pipe name. The client can ask IMS 
to discard the output. 

Unsolicited output should not interfere with half-duplex processing. Thai is, the 
client must be prepared for full-duplex flows while still maintaining a half-duplex 
flow on a user-token level. Contention should not be an error condition. 

Sample Commit-Then-Sericf Transaction Processing Flows 

Figure 4 shows a non-OTMA environment: a secondary logical unit type 2 (SLU 2) 
device communicates with IMS using VTAM and IMS device support (DDMs). The 
transactions are enqueued to the IMS message queues. Transaction output is 
returned to the SLU 2 device. 

O/SSyspisx 




Figure 4, Standard SLU 2 Transaction Flow 

Figure 5 on page 8 shows the same transaction flow in an OTMA environment. The 
transaction still comes from a SLU 2 device, but the device communicates with IMS 
using an OTMA client, through an XCF group, rather than VTAM. 

Figure 5 on page 8 only shows the input flow, which begins with the SLU 2 device, 
goes to the OTMA client, through the XCF group, and ends at the OTMA server. 
The transaction is placed on the message queue, and the application issues get 
unique, insert, and get unique calls. Output follows the same path, in reverse. Of 
course, if a client is to send output to the SLU 2 device, the SLU 2 device must be 
defined to the client, and the client must be able to drive that device. 
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Figure 5. SLU 2 Transaction Flow Using OTMA 

It might seem that the OTMA flow is more complex, and for a SLU 2 device, 
perhaps it is. But you can use OTMA to allow any type of device to communicate 
with IMS, not just VTAM-supported devices. An OTMA client can also act as a 
gateway for another network, such as a TCP/IP network. 



Using Transaction Pipes with OTMA 

An IMS transaction represents a request for IMS to do some work. Many 
transactions also require a response, after IMS has completed the work. So, each 
transaction has a source (the requester) and often a destination (for the response). 

IMS uses the concept of a logical terminal (LTERM) to ensure thai responses are 
associated with the correct requesters. An LTERM uses a queue where the 
transaction output is kept before it is returned to the requester. 

Definition: For each LTERM, IMS maintains a connection between the queue and 
the physical node that receives the output. OTMA does not use an LTERM but still 
must maintain a connection between the client and IMS. This connection is the 
transaction pipe, or tpipe. 

Q: What is a tpipe? 

A: A transaction pipe (tpipe) is a logical connection between a client and the 
server, it is analogous to an IMS logical terminal (LTERM). 

I IMS uses the transaction -pipe name to associate all input and output with a 

I particular client. The association between the transaction output and its ultimate 

I destination (for example, a user at a terminal or a printer) is not made within IMS 

I (as is the case with LTERMs), but is the responsibility of the client. 
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By using a transaction pipe, IMS does not know anything about the actual user of 
the transaction, often a user of the client application. Because IMS does not know 
anything about the actual user, the client has complete control over the output of 
transactions. 

OTMA's use of transaction pipes provides: 

• FiexsbiHty 

Many transaction outputs can flow through the same transaction pipe. 

• Performance 

Transaction pipes give the client the ability to specify and distinguish transactions 
based on their message-flow control and synchronization. 

• Resynchronizatiorj between a client and MS 

Transaction pipes can be either synchronized or non-synchronized. For a 
synchronized transaction pipe, all output messages are serialized through a 
single process, and sequence numbers can be assigned to messages. By 
logging these serialized messages, IMS and the client can resynchronize in the 
event of an outage. 

No resynchronization is required for a non-synchronized transaction pipe. 

• Object orientation 

A transaction can be thought of as an object because OTMA keeps the 
transaction message information (such as user data and transaction-pipe name) 
within the message. 

Figure 6 illustrates how transaction pipes fit in an OTMA client/server environment. 
As shown in Figure 6, transaction-pipe structures reside in the OTMA layer only for 
the server. XCF, which resides in the transport layer, can be thought of as an 
interprocess communication layer, because it provides communication between the 
client process and the server process. 



Client Process IMS Process 



OTMA Layers 
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Transport Layer 
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Figure 8. How Transaction Pipes Fit in an OTMA Client/Server Environment 

Differences in Transaction Pipes 

IMS LTERMs and UNIX pipes both provide a one-way flow for message traffic. An 
OTMA transaction pipe provides a two-way flow. 

The concept of a transaction pipe is applicable to any protocol. In a general way, 
the transaction pipe replaces the IMS LTERM because: 
« Processing is full duplex. 

• Multiple flow-control mechanisms are possible. 

• The logical output entity (in other words, the LTERM) is dissociated from the 
node of the actual user. 



Chapter 1 . Introduction to OTMA 9 



Using Transaction Pipes 

• The transaction pipe is implemented as a protocol rather than as an APi, which 
facilitates a client/server architecture, 

• The transaction pipe sets up a data-control mechanism independent of session 
characteristics, and is therefore transaction specific. 

Message Flow Using Transaction Pipes 

The flow control of transactions is handled by the client. The client dynamically 
binds flow-control parameters to the transaction by querying the transaction 
attributes in the server. Transaction pipes are not usually associated with flow 
control (except for synchronized transaction pipes using half-duplex processing). 

Figure 7 shows the basic message flow between a client and a server, using XCF. 
The order of processing is: 

1 . The client sends a transaction as input to the server (IMS). 

2. The server returns transaction output messages to the client. 




Client XCF Server 



Figure 7. Basic iransaction-Pipe Message Flow 

Within the server, the input transaction and the output messages are organized and 
synchronized using IMS queues, as shown in Figure 8 on page 11. The figure 
illustrates a commit-then-send transaction flow for a non-Fast Path environment. 

The order of processing is: 

1 . The client sends a transaction to the server, and the server enqueues the 
transaction on a message queue. 

2. The transaction is submitted to an application program for processing. 

3. The application program prepares any output for the transaction and commits 
the output during sync-point processing. 

4. The output is returned to the client. 

Related Reading: For information on commit-then-send transactions, see "OTMA 
Commit Processing" on page 16. 
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Figure 8. Use of Queues in the Transaction-Pipe 



Flow 



In a full-duplex environment, transactions and output messages are being sent and 
processed in parallel, as shown in Figure 9 on page 12. This parallelism can be 
maximized by creating a process for every transaction and output message. The 
order of processing is: 

The client sends a transaction (Iran 1} to the server, and the server's 
transaction pipe enqueues the transaction. 

The transaction (Iran 1) is submitted to an application program for processing. 
The application program enqueues any output (Message 1) for the transaction 
(Iran 1). 

The client sends a second transaction (Iran 2) to the server and the server's 
transaction pipe enqueues the transaction. 

The second transaction (Iran 2) is submitted to an application program for 
processing. 

8. The output (Message 1) for Iran 1 is returned to the client. 

The application program enqueues the output (Message 2) for the second 
transaction (Iran 2). 

The output (Message 2) for Iran 2 is returned to the client. 
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Figure 9. Transaction-Pipe Flow in Full-Duplex tnvironment 

Q: Does specifying a transaction pipe as synchronized make the communication 
flow half-duplex? 



A: No. Transaction pipes are always full-duplex. 



Whether the communication flow is actually half-duplex depends on the client. For a 
synchronized transaction pipe, IMS processes all output messages in the order 
received. No new messages are sent for the transaction until IMS has received an 
AGK message for the previous message. A NAK message causes IMS to half all 
output processing for that transaction. 

While this output processing is taking place, the client could be sending new input 
transaction messages to IMS on that synchronized transaction pipe, if the client 
coordinates the sending of transactions with the receipt of IMS output, the client can 
effect half-duplex processing. 
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The OTMA environment includes a server and one or more clients. This chapter 
explains how a client interacts with the server to process IMS transactions. 

The following topics provide additional information: 

• "What is an OTMA Client?" 

• "OTMA Naming Conventions" on page 14 

• "Messages Sent by OTMA Clients" on page 14 
« "OTMA Commit Processing" on page 16 

• "Protecting Transactions with OTMA" on page 27 

• "Client/Server Resynchronization with OTMA" on page 28 

• "OTMA Resynchronization Protocol" on page 32 



What Is an OTMA Client? 

Definition: An OTMA client is a z/OS application program that sends transactions 
to an IMS server and receives output. The application program must be a member 
of an XCF group and use the OTMA protocol. 

Heterogeneous (non-z/OS) networks can connect with z/OS in many ways. 
Figure 10 shows some of the possible applications that use XCF. These include: 

• WebSphere MQ applications 

• OEM applications 

• IMS Connect applications 

• DCE/RPC applications 
« Other IBM applications 

Any of these can connect to an OTMA client to communicate with IMS. 




!MS Connect DCE/RPC i Other IBM 
Application Application 



Figure 10. Applications that use XCF to connect to IMS on z/OS 
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An OTMA client is the gateway by which transactions from outside IMS can enter 
IMS. 

OTMA processing involves: 

1 . A client sends a transaction or command to the server (IMS). 

2, The server returns output to the client. 

OTMA Naming Conventions 

When naming either a client or a transaction pipe, you must adhere to the following 
conventions. The name: 

• Must be character type A (A-Z, 0-9, @, $) 

• Must begin with a non-blank character 

• Must be padded with blanks if shorter than the maximum length (16 for a client 
name, 8 for a transaction-pipe name) 

• Cannot contain embedded blanks 

• Cannot be a reserved word (for example, "TO" or "SECURITY") 

• Cannot begin with "DFS" or "DBCDM" 

• Cannot be an IMS keyword (for example, "LINE" or "NODE") 

In addition, transaction-pipe names cannot: 

• Duplicate an IMS transaction name. 

• Have the same name as the z/OS system console (for example, "WTOR"), IMS 
MTO, or secondary MTO. 

IMS does not perform uppercase translation. If lowercase characters are used, the 
client receives a negative acknowledgment (NAK) response from the server. 

Messages Sent by OTMA Clients 

An OTMA client communicates with IMS by sending messages. First, a user enters 
application data using a device or program that is connected to the client. Next, the 
client adds some information (the message prefix) and sends the message to IMS. 
Output from IMS is sent to the client as a message, and the client uses the 
message prefix to route the data to the correct device or program. 

Parts of the OTIVtA Message Prefix 

The OTMA message prefix has the following sections: 

• Message-control information 

This section includes the transaction-pipe name, message type, sequence 
numbers (if any), and various flags and indicators. 

• State data 

This section includes a destination override (if any), map name, synchronization 
level, commit mode, tokens, and server state. 

• Security data 

This section includes the user ID, user token, and security flags. 

• User data 

This section includes any special information needed by the client. 
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Following the message prefix is the application -data section of the message. This 
section contains either the data to be sent to IMS for processing or the IMS 
response. 

Related Redding- Tor more information on the OTMA message prefix, see 
Chapter 5, "OTMA Message Prefix," on page 71 , 

OTMA fVfessage-Prefix Roles 

Because a message can have a single segment or multiple segments, the following 
rules apply to OTMA message prefixes: 

• Single-segment messages can have the full prefix (message-control information, 
state data, security data, and user data). 

• Only the first segment of multi-segment messages has the full prefix. Subsequent 
segments are sent with only the message-control information and 
application-data sections. 

• Acknowledgment (ACK or NAK) messages sent by IMS only return the first input 
buffer. This message carries the full prefix, and the application-data section (if it 
is included in the client request). 

Sequence Numbers Used by OTMA 

OTMA uses two types of sequence numbers for messages: send-sequence 
numbers and recoverable sequence numbers. Send-sequence numbers and 
recoverable sequence numbers are used differently in OTMA. 

Using Send-Sequence Numbers 

I Send-sequence numbers are used for input and output messages. A client should 

i increment send-sequence numbers for every input message. Send-sequence 

I numbers increment in the output message when IMS sends output to a client. The 

I send-sequence numbers are used for all the OTMA input/output messages. The 

i send-sequence numbers in the input messages are also used to identify 

I multi-segments. 

Example: There is a two-segment OTMA input message. The first segment 
message will have send-sequence number=XXX and segment number=l. The second 
segment message should have the same send-sequence number=XXX and segment 
number=2. OTMA chains the two-segment message together because the send 
sequence numbers are the same. 

OTMA uses send-sequence numbers in the following ways: 

• All ACK and NAK messages from IMS use the send-sequence numbers 
submitted by the client on input. 

• All OTMA commands that IMS sends to the client have send-sequence number 0 
(zero). And, except for the resynchronization flows, these OTMA commands are 
all single segment, 

• Send-sequence numbers for IMS error messages and IMS transaction output are 
set for each transaction pipe. Send-sequence numbers increment by one for 
each message in a given transaction pipe, and it is never 0 (zero). When the 
sequence number exceeds 4 294 967 295 (the 32-bit maximum), it is reset to 1 . 

Using Recoverable Sequence Numbers 

Recoverable sequence numbers are used only to control resynchronization. If a 
client does not support resynchronization, recoverable sequence nu.mber=0 (zero). 
Resynchronization is only valid for synchronized tpipe and commit-then-send 
input/output. Recoverable sequence numbers increment for every input/output 
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message. Resynch support has an added logic to check if the recoverable 
sequence numbers increment properly, if the sequence numbers increment 
incorrectly, a NAK message is sent. Because the resynch is dependent on the 
recoverable sequence numbers, the resynch must be correct for every input/output. 
Recoverable sequence numbers apply to transaction pipes, which use them to 
control resynchronization. 

Related Reading: For more information on resynchronization, see "Client/Server 
Resynchronization with OTMA" on page 28. 



OTMA Commit Processing 

OTMA can control how IMS commits transactions: they can be either 
commit-then-send or send-then-commit. 

Definitions: 

• For commit-then-send transactions (the IMS standard flow), IMS processes the 
transaction and commits the data before sending a response to the OTMA client. 

• For send- then-commit transactions, IMS processes the transaction and sends a 
response to the OTMA client before committing the data. 

Q: What is the major difference between the commit-then-send processing option 
and the send-then-commit processing option? 

A: The commit-then-send processing option commits the transaction output as part 
of sync-point processing, and then delivers the output to the client later. 

The send-then-commit processing option delivers the transaction output first, 
receives an acknowledgment from the client, and then completes the sync-point 
processing. 

Q: What happened to the commit mode 0 and commit mode 1 processing 
options? 

A: Commit mode 0 is now called "commit-then-send", and commit mode 1 is 
called "send-then-commit". Because the terms "commit-then-send" and 
"send-then-commit" are more intuitive when referring to these processing options, 
the terms "commit mode 0" and "commit mode 1" are no longer used. 

Related Reading: For more information on these two commit modes, see "Sample 
OTMA Commit Processing Flows" on page 17. 

For an OTMA transaction, a client can receive one of the following from IMS: 

• An ACK message for the input, followed by any output messages. 

In addition send-then-commit transactions will also receive an ACK message 
followed by a "deallocate" flow (indicated when the commit-confirmation flag in 
the message-control information section of the message prefix is set to either 
Committed or Aborted). 

• A NAK message with a sense code. 

• A NAK message with the processing flag set to Error Message Fol lows in the 
message-control information section of the message prefix. The subsequent 
message has the same message prefix as the NAK message and has the IMS 
error message in the application-data section of the message prefix. 
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ymmary of OTMA Commit Processing 

Table 2 summarizes the differences between commit-then-send and 
send-then-commit processing. Several variables are listed in the first column; the 



differences between processing options are described in the next two columns. 
Following Table 2 are some usage notes to be aware of. 


Tabled, Commit-Then-Send vt 


irsus Send-Then-Commn Processing 


Variables 


Commit thon -send 


Scwi then commit 


Conversational 


Client receives a NAK 
message. 


Supported, 


Fast Path 


Client receives a NAK 


Supported, 


Non-conversational and 
non-Fast Path transactions 


IMS commits after enqueuing 
the output to the client. The 
output is delivered later. 


iMS sends output to the client 
and then commits. 


Enqueue the Input? 


Yes. 


Yes. 


Enqueue the output? 


Yes. 


No. 


Synchronized transaction pipe 
specified? 


Supported. 


Client receives a NAK 
message. 



Notes: 

• IMS conversations cannot use the commit-then-send commit mode. 

• Send-then-commit input and output is irrecoverable. 

• For irrecoverable output (send-then-commit), IMS requests an acknowledgement 
if the synchronization level is set to Confirm. 

• For a recoverable transaction, IMS always requests an acknowledgement for an 
output message. 

• For commit-then-send transactions, IMS always requests an acknowledgement. 

• Synchronized transaction pipes can only be used for commit-then-send 
transactions. 

ample OTMA Commit Processing Flows 

In order to explain the differences between the two commit modes, this section 
shows sample flows of data between IMS and clients for each commit mode. 

Reiated Reading: For more detailed message flows, see "Sample OTMA Message 
Flows" on page 21 . 

Cornmrt-Then-Send Row 

The commit-then-send flow, also known as the IMS standard flow, enqueues IMS 
output before sending it to the client. Use this flow for standard transaction 
processing. To use the standard flow, specify Commit Mode 0 in the state-data 
section of the message prefix. This sample flow assumes the following: 

• The transaction pipe is synchronized. IMS maintains sequence numbers for 
recoverable input and output for the transaction pipe, 

• Acknowledgment is always requested (by both IMS and the client). 

If NAK is received by IMS, then the output is returned to the queue and will be 
delivered later. 
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The flow is illustrated in Figure 11. Following Figure 11 is a sequential list that 
provides more details on the flow. 




Figure 11. Commit-Then-Send (IMS Standard) Flow 

The sequence of the flow illustrated in Figure 11 is: 

Transaction initiated (response required/synchronized tpipe) 
Transaction is inserted to SMB 
ACK 

GU call followed by ISRT to IOPCB 
Sync Point 

Output is enqueued to tpipe, and DB is committed 
Transaction completes 
Output is sent with response requested 
ACK 

10. Output is dequeued. 



An example of the flow of the message activity for a single commit-fhen-send 
transaction pipe is shown in Figure 12. Following Figure 12 is a sequential list that 
provides more details on the flow. 




Figure 12. Sample Message Flow for Commit-Then-Send Flow 

The sequence of flow shown in Figure 12 is: 

1. Tranl 

2. ACK to Tranl 



)pen Transaction Manager Access Guide and Refersnc 



Commit Processing 



3. Tran2 

4. Output of Irani 

5. ACKtoTran2 
8. Tran3 

7. ACKtoTranS 

8. Tran4 

9. ACK to output of Tranl 
10. ACKtoTran4. 

Seocf-Theo-Commit Row 

The send-then-commit flow sends IMS output before IMS completes 
synchronization-point (hereafter referred to as sync-point) processing. To use the 
send-then-commit flow, specify Commit Mode 1 in the state-data section of the 
message prefix. This sample flow assumes the following: 

• The transaction pipe is not synchronized. 

• The synchronization level is specified as None in the state-data section. 
Therefore, IMS does not request a response (an ACK) when sending output. 

The flow is illustrated in Figure 13. Following Figure 13 is a sequential list that 
provides more details on the flow. 



Figure 13. Set 



Then-Commit Flow 



he sequence o! flow shown in Figure 13 is: 

. Transaction initiated 

. Transaction inserted to SMB 

. GU call followed by ISRT to IOPCB 

. Sync point started 

. Output is sent. No response is requested; response is requested only when 

sync=confirir: is specified. 
. Commit confirmed; IMS completed sync point 
. Transaction completes 



An example of the flow of the message activity for a single transaction pipe is 
illustrated in Figure 14 on page 20. Following Figure 14 on page 20 is a sequential 
list that provides more details on the flow. 
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XCF 




Figure 14. Sample Message Flow for Send-Then-Commit Flow 
The sequence of flow shown in Figure 14 is: 



1. 


Irani 


2. 


Tran2 request/response 


3. 


Tran3 request/response 


4. 


ACK to TranS 




Output of Irani 


6. 


ACK to Tran2 


7. 


Tran4 


8. 


Output of Tran4 


9. 


Confirm of Tran4 


10. 


Output of Tran2 


11. 


Output of Tran3 


12. 


Confirm of Tranl 


13. 


Confirm of Tran3 


14. 


Confirm of Tran2 



As shown in Figure 14, the client can receive a confirmation for output before 
receiving the actuai output, because XCF does not guarantee that aii messages are 
sent in sequential order. The ciient must be able to handie this situation during 
message-receipt processing or by using the XCF Message exit routine. 

Q: How can a client know whether or not a send-then-commit transaction ran 
successfully? 

A: OTMA sends message DFS2082 to the client if the IMS transaction ends 
unsuccessfully and does not perform an insert to the IOPCB. 
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Send-Ttien-Commst Row with Confirm 

The send-then-commit flow assumes no synchronization for the transactions as they 
are processed by IMS. This section shows a flow in which all transactions are 
confirmed as they are received {each message requests a response). The sample 
illustrated in Figure 15 assumes the following: 

« Commit Mode 1 is specified in the state-data section of the message prefix. 

• The transaction pipe is not synchronized. 

• The Synchronization Level is specified as Confirm in the state-data section. 

If NAK is received by IMS, then a user 119ABEND occurs in the application and 
IMS issues a DFS554 message to the client. 

Following Figure 15 is a sequential list that provides more details on the flow. 



JMSJJM 



1 






Client 


z 


3 


Application 




4 




b 






5 # 




? 


8 





Figure lb. Send-Then-Commit with Confirm Flow 



The sequence of flow shown in Figure 15 is: 

1 . Transaction initiated 

2. Transaction inserted to SMB 

3. GU call followed by ISRT to IOPCB 

4. Sync point start 

5. Output sent; response requested 
8. ACK 

7. DB is committed; commit is confirmed; IMS completed sync point 

8. Transaction completed 

Sample OTMA Message Flows 

This section shows some sample message flows, and describes how various fields 
in the message prefix are set. In the figures, the following abbreviations are used 
for parts of the message prefix: 

IViC Message-control information section 

SD State-data section 

SE Security-data section 

US User-data section 

AP Application-data section 
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The sample flow diagrams show which parts of the prefix are mandatory for a givers 
message and which are not applicable. Optional fields and prefix sections are 
enclosed in parentheses. 

For transactions submitted by clients, the following principles apply: 

• After IMS sends an ACK message to a client, IMS sends a commit confirmation 
(indicating that the transaction committed successfully or was aborted). 

• The commit confirmation terminates a client transaction. 

Refated Reading: For examples that show what the message prefixes look like for 
various types of messages, see "Sample OTMA Messages" on page 94. 

Client-Bid Message Flow 

Figure 18 shows a client-bid flow, where the client attempts to connect to the server. 
This flow can occur when the client has already joined the XCF group and notices 
that a server has joined the group. The client-bid flow is: 

1. Client-Bid: MC, SD, SE 

2. ACK: MC, SD, SE 




Table 3 shows the contents of the message prefix. 1 The flow step is listed, with the 
message flow type, message prefix section, and associated contents of the 



message pr 


sfix section for the prefixe 


s MC, SD, and SE. 


Table 3. Contents of Client- 


Bid Flow Mes 


sage Prefix 


Flaw Step 


Message 
Flow 


Message 

Prefix 

Section 


Contents of Prefix Section 


1 


Client-Bid 


MC 


Architecture level = 1 

Message type = command 

Response flag = response requested 

Command type = client-bid 

Prefix flag = state data + security data 






SD 


The state data format for command 
messages applies to these fields: 
Length 

Member name 
Originator's token 
Destination token 
(DRU exit name) 
MaxBiocksize 
Aging value 
Hash table size 






SE 


(Utoken) 



1 . The numbers used to show sequence (shown in Figure 16 and in the tabie text) are not part of the actual message prefix, 
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Table 3. Contents of Client-Bid Flow Message Prefix (continued) 



Flo¥/ Step 


Flow 


Message 

SfcOtlQr< 


Coni«.-ni& of Prefix Section 


2 


ACK 


M 


Architecture levei == 1 

Message tyrje = commarid and response 

Response flag = ACK 

Command type = client-Did 

Prefix flag = state data + security data 






SD 


The slate data formal fa xr nand 
messages applies to these fields: 
Length 

Member name 

Destination token 
(DRU exit name) 
MaxBlocksize 
Aging value 
Hash table size 






SE 


Utoken 



Server-Available Flow 

Figure 17 shows a Server-Available flow, where the server attempts to connect to 
the client. This flow only occurs when the server is already joined to the XCF group 
and recognizes that a client joins the group. A client should not wait for the server 
to recognize that if has joined the XCF group; the client should send its client-bid 
message as soon as it joins the group. 

The client should ignore a Server-Available message after it has successfully 
completed its client-bid request and connected to the XCF group. The flow shown 
is: 

1 . Server-available: MC, SD, SE 

2. Client-Bid: MC, SD, SE 

3. ACK: MC, SD, SE 




Figure 17, Server-Available Flow 

Table 4 on page 24 shows the contents of the message prefix. * The flow step is 
listed, with the message flow type, message prefix section, and associated contents 
of the message prefix section for the prefixes MC, SD, and SE. 



2. The numbers used to show sequence (shown in Figure 17 and in the table text) are not part of the actual message prefix. 
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Table 4. Contents of Server-Avanable Flow Message Prefix 



! , Message 

Message < Prefix 
Row Section 



Content of Prefix S«ctiofj 

■ Architecture level = 1 
i Message tvpe = command 
i No response rlag 
Cc r na j type = ^ Tvei i able 



i 1 ne state data format tor commana 
r^js igcs aopiies io the^e fiolos 

■ Length 

i Member name 
i Originators toKen 

■ Destination toKen 



Client-bid ■ MC 



ACK I MC 



i Architecture level = i 

■ Message type = command 

■ Response flag = response requested 
■■ Command type = client-bid 

i Prefix flag = state data + secuntv data 
1 1 ne state data format for commana 
i messages aopiies to these fields: 

■ Length 

i Member name 
i Originator s toKen 

■ Destination toKen 

■ (DRU exit namet 
i MaxtSlocksize 

i Aginq value 

■ Hasn table size 

i (UtoKen) 

I Architecture level = 1 

i Message type = command and respons< 

■ Response flag = ACK 

■ Command type = client-bid 
Pre'ixfag sUfc data t- sex nty oatd 

■ Tr\e stare data format for command 
i messages applies to these fielas: 

i Length 

■ Member name 

! Originators toKen 
i Destination toKen 

■ {DRU exit name) 

■ MaxBlocksize 
i Aging value 

I Hash table size 



Commit~Then~Seod Transaction Flow 

Figure 18 on page 25 shows the flow for a commit-then-send transaction, where the 
client submits a transaction to the server for processing. The flow is: 

1 . Transaction ABC: MD, SD, SE, (US), AP 

2. ACK: MC, SD, SE, (US) 

3, Transaction output: MC, SD, (US), AP 

4, ACK: MC, SD 
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Figure 18. Commit-Then-Send Transaction Flow 

Table 5 shows the contents of the message prefix. 3 The flow step is listed, with the 
message flow type, message prefix section, and associated contents of the 
message prefix section for the prefixes MC, SD, SE, US, and AP. 



Table 5. Contents of Commit-Then-Send Transaction Flow Message Prefix 



Flow 
Step 


Message Flow 


Message 

Prefix 

Section 


Content of Prefix Section 




Transaction 
^ABC- 


MC 


Architecture level = 1 
Message type = transaction 
Response flag = response requested 

Prefix flag = SD/SE/(US)/AP 
Send-sequence number 






SD 


Length 

Synchronization level = Gonfirm'or None 

(Map name) 

(Correlator) 

Length of server user data = 0 






SE 


Length 

(Security flag) 
Length of fields 
User ID length 
(User ID type = 02) 
(User ID) 
Profile length 
(Profile type = 03) 
(RACF® group) 
Utoken length 
(Utoken type = 00) 
(Utoken) 






(US) 


This optional section is returned 
with the transaction output: 
Length 
User data 






AP 


Length 
ZZ 

application data ('ABC In the example) 



3. The numbers used to show sequence (shown in Figure 18 and In the table text) are not part of the actual message prefix. 
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Table 5. Contents of Commit-Then-Send Transaction Flow Message Prefix (continued) 



FSgw 


Flow 


Message 

Prefix 

Section 


Consons os Prefix Soctson 


2 


ACK 


MC 


Architecture level = 1 

Message type = transaction and response 
Response flag = ACK 
Transaction-pipe name 
Prefix flag = SD/SE 
Send-sequence number 






SD 


Length 

Synchronization flag = Commit Mode 0 
Synchronization level = Confirm or None 
(Map name) 
(Correlator) 

Length of server user data = 0 






SE 


Length 

(Security flag) 
Length of fields 
User ID length 
(User ID type = 02) 
(User ID) 
Profile length 
(Profile type = 03) 
(P.ACF group) 
Utoken length 
(Utoken type = 00) 
(Utoken) 






(US) 


This optional section Is returned with the 
transaction output: 
Length 
User data 


3 


Transaction 
Output 


MC 


Architecture level = 1 

Message type = data 

Response flag = response requested 

Transaction-pipe name 

Prefix flag = SD/(US)/AP 

Send-sequence number 

Server token 






SD 


Length 

Synchronization flag = Commit Mode 0 
Synchronization level = Confirm or None 
(Map name) 
Server token 
(Correlator) 

Length of server user Data 
(Server user data) 








transaction output: 

Length 

(User data) 






AP 


Length 
ZZ 

Transaction output data 
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Table 5. Contents of Commit-Then-Send Transaction Flow Message Prefix (continued) 



Flow 




Message 






lv1&Se$£3Cfc' Flow 




ConUini of Fr^fYx Soclion 




a;k 


MC 


Architecture levei = 1 

Message ryoe = data and response 

Response flag = AuK 

Transaction-pipe name 

Prefix rlag = SD 

Send-sequence number 






SD 


Length 

^ynch c nizat >n flag = Cor n * Mooo 0 
synchronization level = Confirm or None 
(Map name) 
Server token 
(Correlator) 

Length of server user data 
(Server user data) 



Protecting Transactions with OTMA 

This section describes protected transactions, how to use them, and the roie of 
OTMA, APPC/IMS, and RRS in protecting transactions. 

In a z/OS environment, this resource protection and recovery is managed by 
Resource Recovery Services (RRS), part of z/OS Recovery Resource Management 
Services (RRMS). RRS can apply coordinated changes across multiple 
mission-critical resources. 

OTMA is one of two components that enable IMS to support protected transactions. 
The second component is APPC/IMS. 

To process protected transactions, specify RRS=Y on the control region JCL. IMS 
then registers as a Resource Manager (RM) with RRMS using the CRGGRM 
service; it also sets its exits with the Context Services and RRS exit managers 
using the CRGSEIF service. IMS supports the following RRS exit routines: 

• PREPARE 

• COMMIT 

• BACKOUT 

, EXIT. FAILED 

• ONLY_AGENT 

• SUBORDINATE...FAILED 

During initialization, IMS issues message DFS8653I to indicate that it has 
successfully connected with RRS and that it can now process protected 
transactions. 

Initiating Protected Transactions from an OTIVtA Ciient 

Following are the steps to initiate protected transactions from an OTMA ciient. 

1 . Specify Sync!evel=2 (Syncpt) in the OTMA message prefix. 

2. Obtain or reuse a context token. To obtain a context token, use the CTXBEGC 
service. 
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3. Set the context token in the OTMA message prefix. 

4. Express interest in the UR using ATREINT. 

5. Send the [message to the OTMA client. 

6. Wait for the output from the IMS transaction. 

7. Send an acknowledgement (ACK) to IMS after the output is received, 

8. Initiate the RRS commit (ATRACMT) or backout (ATRABCK). 

The OTMA client assumes the server distributed syncpoint RM (SDSRM) roie. This 
means that the OTMA client owns the context and is the only RM allowed to initiate 
or invoke the RRS commit. The flow is similar to that of an APPC/iMS- protected 
transaction, with the following exceptions: 

• The OTMA client initiates the commit using the RRS Commit_Agent_UR service 
(ATRACMT). 

• RRS then directly informs IMS to take a commit. As a result of the previous 
ATRACMT call, RRS drives the commit exits of all interested RMs. 



Processing Protected Transactions in IMS 

IMS receives the protected transaction and extracts the context token from the 
OTMA message header. IMS saves the context token in its own control block before 
placing the protected transaction on the IMS message queue. Also, before placing 
the protected transaction on the message queue, IMS expresses interest in the 
context using the Express ..Context,, .Interest service (CTXEINT). IMS will therefore 
be informed if anything happens to the context while the protected transaction is 
queued on the message queue. 

When IMS schedules the protected transaction into a dependent region, IMS 
switches the context token to the dependent region TCB using the Switch_Context 
service (CTXSWCH); it also expresses protected interest in the UR using ATREINT. 
IMS then presents the protected transaction to an application program that 
processes that particular transaction. The application contains the business logic 
(for example, update databases, send messages, and others). After the application 
completes its work, it reaches a commit point. IMS then sends the application 
output back to the OTMA client and waits for a commit or backout event from RRS. 



Client/Server Resytichronization with OTIWIA 

In order to guarantee that client transactions are processed and that they are 
processed only once, OTMA provides a protocol for synchronizing transactions. 
Using a synchronized commit-then-send (Commit Mode 0) transaction pipe, the 
client and IMS can regain message flow in the event of a client or IMS outage. 
Resynchronization occurs when either IMS or the client terminates normally or 
abnormally. 

Transaction resynchronization achieves the following: 

• Prevents data from being reprocessed 

• Detects that data has not been received and causes the client to resend the data 

• Detects that resynchronization might not be possible 

• Allows the client to decide what actions to take in order to resynchronize 
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OTMA resynchronization is not symmetrical, and a system's behavior depends on 
its role: client or IMS. Resynchronization also does not maintain symmetry for send- 
er receive-sequence numbers. For example, the differences for the input and output 
sides of an IMS flow are: 

input IMS logs the client sequence numbers when the transaction is 

enqueued, and from that moment, the client has no control over 
dequeuing the transaction. 

Output The application output is enqueued to a synchronized transaction 

pipe, but the output sequence numbers are not logged at that time. 
Only after sending the output and receiving an acknowledgment 
from the client does IMS finally dequeue the message and log the 
incremented sequence numbers. 

All output using a synchronized transaction pipe is sequenced. The second output 
message is not sent until the ACK message from the client is received for the first 
output message. 

Q: Why would I use a synchronized tpipe versus a nonsynchronized tpipe? 

A: Use a synchronized tpipe to ensure that client transactions are processed only 
once in the case of a client or IMS failure. Therefore, synchronized tpipes ensure 
better transaction recoverability. However, in order to guarantee transaction 
recovery, you are required to implement resynchronization logic with synchronized 
tpipes. 

Use a nonsynchronized tpipe when the recoverability of a transaction is less of a 
concern. For nonsynchronized tpipes, the client does not require the 
resynchronization logic. 

Assumptions for OTIVfA Resynchronization 

The OTMA resynchronization process is based on the following assumptions: 

• Neither client nor IMS sends an ACK message until it has logged a transaction 
message. 

• The client decides what resynchronization actions IMS should take. 

• Both client and IMS can determine whether a transaction and its output 
messages are recoverable. The client can determine a transaction's recoverability 
using the architected form of the /DISPLAY TRANSACTION command. 

• Recoverable OTMA messages include a value for the recoverable sequence 
number in the message-control information section of the message prefix. This 
value is incremented by 1 every time a recoverable message is sent using a 
tpipe (see Table 6 on page 30, Table 7 on page 31 , and Table 8 on page 31). 

« A 0 (zero) is not a valid recoverable sequence number. 

• Recoverable send- and receive-sequence numbers are maintained on a per 
transaction pipe basis. 

• IMS does not support resynchronization for any IMS command input. If the client 
needs to submit IMS commands using a synchronized transaction pipe, the 
recoverable sequence number must be set to 0 (zero), if the recoverable 
sequence number is not set to 0 (zero), IMS rejects the command input with 
sense code X'0023'. 
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Recoverable OTIVfA Transactions 

The recoverability of OTMA-initiated transactions and commands is determined by 
the following factors: 

• Is it a recoverable or unrecoverable transaction? 

• Is it a recoverable or unrecoverable command? 

• Is the recoverable sequence number 0 (zero) or not? 

• Is it a synchronized or nonsynchronized transaction pipe? 

• Is it Commit Mode 0 (commit-then-send) or Commit Mode 1 (send-then-commit)? 

A recoverable IMS transaction submitted using the send-then-commit transaction 
flow is not rejected. However, send-then-commit transactions are discarded during 
IMS restart (they are unrecoverable). 

Q: Are transactions using synchronized transaction pipes recoverable? 

A: Yes. Input messages are not recoverable for send-then-commit transactions, 
and requesting an ACK message has no effect on whether a transaction is 
recoverable. You should request ACK messages for proper synchronization of the 
synchronized transaction pipe. 

Also, when a transaction reaches IMS, its recoverability depends on how it is 
defined to IMS. 

Unrecoverable OTMA Transactions 

The following is true for unrecoverable transactions: 

• The client must know that the transaction is unrecoverable, process it, and then 
forget about it, 

• Send-then-commit output is unrecoverable, and it is not resynchronized. 

• Send-then-commit transactions must be associated with nonsynchronized 
transaction pipes. 

Summary Results of IMS Transactions and Commands 

Table 6 summarizes the results of IMS transactions that a client submits under 
various processing conditions using a synchronized tpipe. The summarization 
differentiates recoverable sequence numbers of zero and non-zero, and shows the 
differences between recoverable and unrecoverable transactions for commit modes 
0 and 1 for both the zero and non-zero sequence. 



Sequence Number 



Commit-Then-Send (Commit Mode 0) Send-Then-Commit (Commit Mode 1} 

Recoverable 
Transaction 



Recoverabie 



0 (zero) 



Ghent receives ACK 
message. Output is 
recoverable, and no 
input/output 
recoverable sequence 
Is updated. 



Un recoverabie 
Transaction 

Client receives ACK 
message. Output is 
not recoverabie and 
no input/output 
recoverable sequence 
number is updated. 



Recoverabie 
Transaction 

Client receives NAK 
message with sense 
code X'OOIC. 



Unrecoverable 
Transaction 
Client receives NAK 
message with sense 
code X'OOIC 
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Table 6. Results of IMS Transactions Using a Synchronized Tpipe (continued) 



Commit-Then-Send (Commit Mode 0) Send-Then-Commit (Commit Mode 1) 

Sequence Number i^o've'r'abie " 
Transaction 



Recoverable 



Not 0 (zero) 



If the recoverable 
sequence number Is 
valid, client receives 
ACK message, if it is 
not valid, client 
receives NAK 
message with sense 
code X'001 F, 
Transaction and 
output are 
recoverable. 



Unrecoverable 
Transaction 

Client receives NAK 
message with sense 
code X'0023". Client 
should set 

recoverable sequence 
number to 0 (zero). 



Recoverable 
Transaction 

Client receives NAK 
message with sense 
code X'001 C. 



Unrecoverable 
Transaction 

Client receives NAK 
message with sense 
code X'001 C 



Table 7 summarizes the results of IMS transactions that a client submits under 
various processing conditions using a nonsynchronized tpipe. The summarization 
differentiates recoverable sequence numbers of zero and non-zero, and shows the 
differences between recoverable and unrecoverable transactions for commit modes 
0 and 1 for both the zero and non-zero sequence. 



Table 7. Results of IMS Transactions Using a Nonsynchronized Tpipe 



Recoverable 


Commit-Then-Send (Commit Mode 0) 


Send-Then-Commit (Commit Mode 1) 


Sequence Number 


Recoverable Unrecoverable 
Transaction Transaction 


Recoverabie Unrecoverable 
Transaction Transaction 


0 (zero) 


Client receives ACK Client receives ACK 
message. Transaction message. Transaction 
and output are and output are not 
recoverable. recoverable. 


Client receives ACK Client receives ACK 
message. Transaction message. Transaction 
and output are not and output are not 
recoverable. recoverable. 



Client receives NAK 
message with sense 
code X'0023'. Client 
should set 

recoverabie sequence 
number to 0 (zero). 



Client receives NAK 
message with sense 
code X'0023'. Client 
should set 

recoverable sequence 
number to 0 (zero). 



Client receives NAK 
message with sense 
code X'0023'. Client 
should set 

recoverabie sequence 
number to 0 (zero). 



Client receives NAK 
message with sense 
code X'0023'. Client 
should set 

recoverable sequence 
number to 0 (zero). 



Table 8 summarizes the results of commands that a client issues under various 
processing conditions using a synchronized tpipe or a nonsynchronized tpipe. The 
summarization differentiates recoverable sequence numbers of zero and non-zero, 
and shows the differences between commit modes 0 and 1 for both synchronized 
and nonsynchronized tpipes. 



Table 8. Results of Commands that a Client issues 



Recoverabie 


Synchronized Tpipe 


Nonsynchronized Tpipe 


Sequence Number 


Commit-Then-Send Send-Then-Commit 
(Commit Mode 0) (Commit Mode 1) 


Commit-Then-Send Send-Then-Commit 
(Commit Mode 0) (Commit Mode 1) 


0 (zero) 


Client receives ACK Client receives NAK 
message. Command message with sense 
output is recoverabie code X'001 C, 
and output 

recoverabie sequence 
number is updated. 


Client receives ACK Client receives ACK 
message. Output is message. Output is 
not recoverable. not recoverable. 
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Table 8. Results of Commands that a Client Issues (continued) 



Synchronized Tpipe Nonsynchronssed Tpspe 



Recoverable 
Sequence Number 



Not 0 (zero) 



Commit-Thera-Sersd 
(Commit Mode 0) 

Client receives NAK 
message with sense 
code X'0023'. Client 
should set 

recoverable sequence 
number to 0 (zero). 



Send-Thers-Commit 
(Commit Mode 1) 

Client receives NAK 
message with sense 
code X'OOIC 



Commit-Then-Sersd 
(Commit Mode 0) 

Client receives NAK 
message with sense 
code X'0023 ! . Client 
should set 

recoverable sequence 
number to 0 (zero). 



Serad-Thers-Gornmit 
(Commit Mode 1) 

Client receives NAK 
message with sense 
code X'0023', Client 
should set 

recoverable sequence 
number to 0 (zero). 



Related Reading: 

• For information on the differences between recoverable and unrecoverable IMS 
transactions, see SMS Version 9: Administration Guide: Transaction Manager. 

• For information on recoverabilify of APPC transactions in these circumstances, 
see "integrity Tables" in SMS Version 9: Application Programming: Design Guide. 



OTMA Resyochronization Protocol 

OTMA resynchronization is based on the following command exchanges for each 
ciient: 

CBresynch (Ciient_Bid resyrseh) 

CBresynch is sent by the client to request resynchronization with IMS after 
both the client and IMS have successfully joined the XCF group. 

SRVresyrsch {Serves- resynch) 

SRVresynch must be initiated from IMS to the ciient after the ciient has 
successfully joined the XCF group and issued CBresynch. SRVresynch 
contains all synchronized tpipe names of which IMS is aware. 

REGresyrtch (Request resynch) 

REQresynch must be issued from IMS to the client for each Synchronized 
tpipe, REQresynch contains the tpipe name, the IMS recoverable 
send sequence number for the tpipe, and the IMS recoverable receive 
sequence number for the tpipe. 

REPresyrsch (Reply resyrseh) 

REPresynch is issued from the client for each tpipe. REPresynch is a reply 
to the REQresynch request from IMS. 

TBresymeh (tpspe__Bid resynch) 

Tpipe....Bid resynch is issued by the client to initiate resynchronization with 
IMS for a particular tpipe. 

IMS keeps track of the send and receive numbers in the tpipe structure. The send 
and receive numbers are updated for each input and output message. When 
resynch occurs, both the client and IMS share their send and receive numbers to 
verify that both sides are synchronized. The REQresynch command from IMS 
releases the send and receive numbers from IMS. The client accepts the numbers 
and does a comparison to the client's send and receive numbers, if the send and 
receive numbers are not the same, then the client specifies an action to IMS with 
the REPresynch command. If both sides have the same send and receive numbers, 
then the resynch completes successfully, if resynch fails, then the failing tpipe is 
identified and is not used. 
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Command message exchange for resynchronization must follow the OTMA 
resynchronization protocol. Normally, the sequence of events that occurs during 
resynchronization is: 

1 . The client issues CBresynch when the client attempts to resynchronize with 
IMS. 

2. IMS sends an ACK to acknowledge receipt of CBresynch, From this point on, 
IMS quiesces any non-resynch type of input or output for all synchronized 
tpipes. if IMS receives input while resynchronization is in progress for a 
synchronized transaction pipe (tpipe), the input is rejected with sense code 
X'0025'. 

3. IMS builds the SRVresynch command and sends it to the client. The 
SRVresynch command lists all synchronized tpipe names of which IMS is aware 
for that client. 

4. The client receives the SRVresynch command and issues an ACK or NAK 
message to IMS. 

5. If IMS receives an ACK message, IMS begins the resynchronization process for 
each tpipe. IMS sends the REQresynch command that contains the tpipe name, 
the IMS recoverable send-sequence number for the tpipe, and the IMS 
recoverable receive-sequence number for the tpipe. 

if IMS receives a NAK message from the SRVresynch command, IMS sends the 
DFS2393 message to the MTO and waifs for a client-bid request or a 
CBresynch command from the client. 

6. The client receives the REQresynch request. By comparing the information from 
the REQresynch request with its own information of the tpipe, the client sends 
the REPresynch reply to IMS and informs IMS about the tpipe 

Related Readirtg: For more information on REPresynch format, see "Format of 
OTMA State Data for REPresynch Command" on page 85. 

7. IMS receives the REPresynch reply and takes actions on the tpipe, based on 
the information from the client, IMS sends an ACK message to the client after it 
has taken actions dictated by the client. IMS enables the tpipe to handle input 
and output, if IMS cannot perform what the client has requested, IMS stops the 
tpipe and sends a NAK message to the client, 

8. if more than one tpipe exists, steps 5 to 7 are repeated in parallel for each 
tpipe. Other tpipes that are not included in the SRVresynch request can send 
output in either direction anytime after step 4. 

Figure 19 illustrates the flow of nondeferred resynchronization. Following Figure 19 
is a sequential list that provides high-level flow description. 
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Figure 19. Flow of Resynchronization (Nondeferred) 



1 . Client-bid request with resynchronization 

2. ACK message 
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3. SRVresynch command 

4. ACK message 

5. REQresynch command 

6. REPresynch command 

7. ACK or NAK message 

If the client determines that resynchronization must be deferred for a particular 
tpipe, the sequence of events for that tpipe differs slightly: 

In the REPresynch command, the client can set the "stop and wait for 
resynchronization" indicator, and can request that IMS defer any input or output 
while waiting for the TBresynch command from the client. Assuming steps 1 on 
page 33 to 4 on page 33 have completed, the events following are: 

1 , IMS sends the REQresynch command that contains the tpipe name, the IMS 
recoverable send-sequence number and the IMS recoverable receive sequence 
number 

2, The client receives the REQresynch request. However, due to any 
product-specific reasons, the client defers resynchronization for this tpipe by 
sending the REPresynch command with the "stop and waif for TBresynch" 
indicator on. 

3, IMS sends an ACK message to acknowledge receipt of the REPresynch 
command and waits for TBresynch. Meanwhile, IMS quiesces input and output 
for the tpipe. if IMS receives any input white waiting for TBresynch, IMS sends a 
NAK message to the client with sense code X'G025\ 

4, The client sends the TBresynch command and requests IMS to resume 
resynchronization for this tpipe. 

5, IMS sends the REQresynch command that contains the tpipe name, the IMS 
recoverable send-sequence number, and the IMS recoverable receive-sequence 
number. If the associated tpipe cannot be located using the client's TBresynch 
command, the client receives a NAK message with sense code X'0Q25'. 

8. The client receives the REQresynch request. By comparing the information from 
REQresynch request with its own information about the tpipe, the client sends 
the REPresynch reply to IMS and informs IMS about the tpipe. 

7. IMS receives the REPresynch reply and takes actions on the tpipe, based on 
what the client has requested. IMS sends an ACK message to the client if it has 
taken actions dictated by the client. Otherwise, IMS sends a NAK message to 
the client with sense code X'0025' or X'0028 ! . 

Figure 20 shows the flow of deferred resynchronization. Following Figure 20 is a 
sequential list that provides high-level flow description. 

1 

3 
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Figure 20, Flow of Resynchronization (Deferred) 
34 Open Transaction Manager Access Guide and Reference 




OTl^A Resynchronization Protocol 



REQresynch command 

REPresynch command with STOP AND WAIT for TBresynch 
ACK message 
TBresynch command 
REQresynch command 
REPresynch command 
ACK or NAK message 

Sample OTMA Resynchronization Message Flow 

This section provides a sample message flow for OTMA resynchronization. 

Figure 21 shows the fiow of messages through a synchronized transaction pipe. 
Receive- and send-sequence numbers for each side (IMS and client) are 
represented by the letters R and S, which are set in the message-control 
information section of the message prefix. These numbers apply to the entire 
message (including multi-segment messages). R and S are not necessarily related. 
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Figure 2 1. Sample OTMA Resyncnromzation Mess 



e Fiow 



§] After the client submits the transaction, IMS enqueues the transaction, and 
the transaction runs. The receive- sequence number is incremented by 1 . 
|| IMS sends the client an ACK message to acknowledge receiving and 
enqueuing the transaction. 

HI IMS enqueues the output and sends the data to the client. 
|| The client sends an ACK message to IMS to acknowledge receiving the 
output; however, IMS never receives this ACK to message 15 because of an 
IMS failure. 

Resynchronization proceeds as follows: 

fH The client sends a client-bid request to IMS to initiate resynchronization. 
II IMS sends an ACK message to the client that resynchronization will begin. 
§| IMS sends the SRVresynch command to the client to begin 
resynchronization. 
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HI The client sends an ACK message to IMS to acknowledge receiving the 
SRVresynch command. 

II IMS sends the REQresynch command to the client to update the receive- 
and send-sequence numbers to (9,14). 

|p| The client sends the REPresynch command to IMS to update the receive- 
and send-sequence numbers to (15,9), and to tell IMS to dequeue the last 
output message. IMS dequeues message 15 and updates S to 15. 
HI IMS sends an ACK message to the client. 



Sample OTIVIA Resyochrooization Messages 

This section provides sample OTMA resynchronization messages. 

Related Reading: For information on the format of these messages, see Chapters, 
"OTMA Message Prefix," on page 71. 

Figure 22 shows the OTMA client-bid request with the resynchronization message. 

MESSAGE CONTROL INFORMATION: 



.MQXCF6 

. DFSYDRUO. . 



STATE DATA : 

0036D4D8 E7C3C6F6 4Q40404Q 40404040 
4040010Q 00010002 00010100 00020002 
0002C4C6 E2E8C409 E4F00800 00007FFF 
FFFF00O0 O0650056 C35251O0 5O01A051 

Figure 22, Client-Bid Request with Resynchronization Message 

Figure 23 shows the ACK message to acknowledge receipt of CBresynch. 

MESSAGE CONTROL INFORMATION: 



STATE DATA: 

0036D4D8 E7C3C6F6 40404040 4040404O ..MQXCF6 

40400100 00010002 00010100 00020002 .............. 

0002C4C6 E2E8C4D9 E4FO08O0 00007FFF ..DFSYDRUO....". 

FFFF00O0 O0650056 C35251O0 5001A051 ....... .C. ..&. . 

Figure 23, ACK Message To Acknowledge Receipt of CBresym 
Figure 24 shows the SRVresynch command message. 

MESSAGE CONTROL INFORMATION: 



STATE DATA: 

000AD1C2 D1F0F0F0 F0C5000O 00000000 j . , JBJO00OE. . 
Figure 24. The SRVresynch Command Message 
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Figure 25 shows the ACK message sent by client to acknowledge receipt of 
SRVresynch. 

MESSAGE CONTROL INFORMATION : 

0130A000 2C000000 00000000 0000A080 j j 

0O00O0QO 00000000 00000000 00010000 |. ....... ........ I 

STATE DATA: 

000AD1C2 D1F0F0F0 FOC5O00O 00000000 |..JBJ0000E | 

Figure 25. ACK Message To Acknowledge Receipt of SRVresynch 
Figure 28 shows the REQresynch command message. 

MESSAGE CONTROL INFORMATION : 

01100000 300QD1C2 D1F0F0F0 F0C5A080 | JBJ0000E. . j 

00000000 00000000 00000000 00000000 j ................ j 

STATE DATA: 

001AD1C2 D1F0F0F0 F0C50000 00020000 |..JBJ0O00E j 

00020000 00000000 00000000 00000000 j ................ j 

Figure 28. The REQresynch Command Message 

Figure 27 shows the REPresynch command message. 



MESSAGE CONTROL INFORMATION: 

01100000 3400DIC2 D1F0F0F0 F0C5A080 j . . . , . . JBJ0OQ0E. , 

00000003 00000000 00000000 00000000 I ............... . 

STATE DATA: 

0OIADIC2 D1F0F0F0 F0C50000 00020000 j . . JBJ0000E. . , . . , 

00020000 00000000 00000000 00000000 I ............... . 



Figure 27. The REPresynch Command Message 

Figure 28 shows the ACK message sent by IMS to inform the client that 
resynchronization on a tpipe successfully completed. 

MESSAGE CONTROL INFORMATION: 

01308000 3400D1C2 D1F0F0F0 F0C5A080 j JBJ00Q0E. . j 

00000003 00000000 00000000 00000000 [ ................ j 

STATE DATA: 

001AD1C2 D1F0F0F0 F0C50000 00020000 |..JBJ00O0E j 

00020000 00000000 00000000 00000000 [ ................ j 

Figure 28. ACK Message for Successful Resynchronization 
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This chapter describes changes to IMS tasks for the OTMA environment, as well as 
how IMS operates in an OTMA environment. 

The following topics provide additional information: 

• "Installing OTMA" 

• "Customizing IMS for OTMA" on page 42 

• "Administering IMS for OTMA" on page 45 
« "OTMA Restrictions" on page 50 

• "Managing System Resources and OTMA" on page 51 

• "Establishing Security for OTMA" on page 52 

• "General OTMA Security Considerations" on page 55 

• "Using DL/i Calls in an OTMA Environment" on page 55 

« "OTMA Program-to-Program Switch Processing" on page 56 

• "IMS Commands Using OTMA" on page 60 

• "IMS Messages introduced by OTMA" on page 63 



Installing OTMA 

Q: What software do I need to use OTMA? 
A; You need the following software: 

• IMS: minimally IMS/ESA® Version 5, or subsequent versions, releases, and 
modification levels, 

• An operating system: minimally MVS/ESA™ Version 5, or subsequent versions, 
releases and modification levels. 

• An OTMA client: use a client provided by IBM, by another vendor, or write your 
own client. 

OTMA is not installed using the IMS INSTALL/1 VP Dialog. To enable IMS to use 
OTMA, specify the XCF group name during system definition. To start OTMA, you 
can use the 0TMA=Y startup parameter in the IMS procedure during IMS system 
definition. 

Reiated Reading: For more information on IMS system definition, see IMS Version 
9: Installation Volume 2: System Definition and Tailoring. 

Specifying OTIrVlA-Relatecl Parameters 

These are the OTMA-reiated parameters thai you must specify in IMS PP.OCLIB 
member DFSPBxxx: 

ORNATE- 

Specifies the XCF group IMS is to join. The group name is one to eight 
uppercase alphanumeric characters or other valid characters ($, @). 

IMS joins the XCF group either during IMS initialization (if 0TMA=Y is specified) 
or as a result of an IMS /START OTMA command, if GRNAME= is not specified and 
0TMA=N is specified, IMS cannot join the XCF group. 
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If you specify GRNAME= and OTMA is started, you can use the /DISPLAY OTMA 
command to display the XCF status. You are not required to define any XCF 
information. 

Ail OTMA clients must know the XCF group name. The group name for the 
OTMA clients and the IMS server must be the same. 

if you use RACF for security, the IMSXCF. group. member (client member name) 
must be defined in the RACF FACILITY class. 

Specifies whether OTMA is to be enabled. Values are Yjfi The default is N. 

if you specify a valid group name for GRNAME=, you can use the /START OTMA 
command to enable OTMA later, even if you specify QTMA-N during system 
definition. 

OTMAASY- 

Specifies that a non-response transaction originating from a 
program-to-program switch be scheduled asynchronously. This parameter is for 
send-then-commit messages only. A DFS2082 message is not issued for a 
transaction scheduled asynchronously. 

OTMAASY== can also be used in a multiple program-to-program switch 
environment to ensure that only the response transaction be scheduled 
synchronously. 

The default is OTMAASY=N. 

otmanm= 

Specifies the XCF member name that IMS uses for the group when IMS is not 
using Extended Recovery Facility (XRF) or RSR. The member name is 1 to 16 
uppercase alphanumeric characters or other valid characters {$, @), 

The OTMANM name can be specified in the IMS procedure or in the DFSPBxxx 
member, if OTMANM is not specified, IMS uses the IMS APPLID for the 
member name. 

if IMS is using XRF or RSR, the XCF member name that IMS uses comes from 
the USERVAR name specified in the IMS procedure, in the DFSPBxxx member, 
or in the DFSHSBxx member. The OTMANM name is not used in this case. 

Recommendation: Do not change the group name or the IMS member name 
during an IMS emergency or normal restart. 

OTMAMD= 

Specifies whether you want to have the member override function in the 
DFSYPRXO user exit for a transaction invoked from an OTMA client. The 
parameter values are Y (Yes) or N (No). N means that for transactions that are 
invoked from a non-OTMA iterm, you can use the 16-byte member override field 
of the user exit parameter list to specify the OTMA client member name. You 
cannot, however, use the member override field for transactions that are 
invoked from an OTMA client. N is the default setting for the OTMAMD 
parameter. Y means that you can use the member override field of the user exit 
parameter list for both OTMA and non-OTMA invoked transactions. 

Using the OTMASP parameter provides the same function as setting the output 
flag of the OTMA destination resolution exit DFSYDRUO. Using an output flag in 
DFSYDRUO indicates whether a synchronized tpipe needs to be created for 
OTMA output. If the only reason you code DFSYDRUO is to set that output flag, 
you can use the OTMASP parameter instead. 
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The OTMASP parameter values are Y (Yes) or N (No). N. which is the default, 
means that non-synchronized tpipes are to be created for the OTMA output. Y 
means that synchronized tpipes are to be created for OTMA output. 
If your organization uses both the DFSYDRUO exit and the OTMASP parameter 
to control the kind of tpipe that gets created for OTMA output, the following 
table shows when synchronized tpipes will get created. Table 9 describes which 
tpipes are created when the DFYDRUO exit is used, and when OTMASP=Y or 
OTMASP=N. 



Table 9. 1 pipes created when ooth OlMASP parameter and UF-YDHUO exit usees 



DFSYDR' '0 is set to 
Creale &y ;h oni'xi Epipc 


if OTMASP=Y sosuit is If OTMASP=N result >s 

Synchronized tpipe i Synchronized toipe 


Create non-synchronized 
tpipe 


Synohronizea tp.pe 


Non-syncnronizea tpipe 



OTMASE™ 

Specifies the type of OTMA RACF security that you want to use, if any. The 
parameter values are as follows: 

C OTMA RACF security is CHECK. IMS commands are checked against 
the CIMS class. IMS transactions are checked against the TIMS class. 

F OTMA RACF security is FULL. The same type of security as CHECK, 
but additional checking is performed against dependent regions. F is 
the default value for the OTMASE parameter. 

H OTMA RACF security is NONE. No calls to RACF are made. 

P OTMA RACF security is PROFILE. Each OTMA message defines the 
level of security checking to be done. 

Important: The /SECURE OTMA command overrides the value specified in the 
OTMASE parameter. 

Specifying OTMA Descriptors 

OTMA descriptors relate the client name with the OTMA Destination Resolution exit 
routine to be used. OTMA descriptors are optional, if no client descriptor is 
specified, the default exit routine, DFSYDRUO, is used. DFSYDRUO can be 
overridden during a client-bid request. 

OTMA descriptors are built during IMS initialization. The descriptors are included in 
DFSYDTx members of IMS.PROCLIB ("x" is the IMS nucleus suffix). All parameters 
are delimited with a blank. The following is the format of a descriptor: 

Column Contents 

1 Descriptor type. M is for an OTMA descriptor. 

2 Blank. 

3-18 1- to 16-character client name, left-justified and padded with blanks 

if necessary. This is a required and positional parameter. Duplicate 
names are not allowed. 

The client name should follow the resource naming conventions. 

Related Reading: For more information on the naming 
conventions, see "OTMA Naming Conventions" on page 14. 

19 Blank. 
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20-23 DRU= 

24-31 OTMA Destination Resolution exit routine name. This is a required 

parameter. Duplicate exit routine names are allowed. 

73-80 Sequence numbers. These columns are ignored by IMS. 

If you have multiple clients at the same IMS system, list each client name on a 
separate line. Ensure that columns 3-18 are different for each client. 



Customizing IMS for OTMA 

This section describes the exit routines that you can use to customize IMS for 
OTMA. 

OTMA-Supported Exit Routines 

Three new exit routines support OTMA: 

• OTMA Destination Resolution (DFSYDRUO) 

• OTMA Input/Output Edit (DFSYIOE0) 

• OTMA Prerouting (DFSYPRXO) 

In addition, the following exit routines are supported by OTMA: 

• Command Authorization (DFSCCMDO) 

• Input Message Routing (DFSNPRTO) 

• Queue Space Notification (DFSQSPCO) 

• Transaction Authorization (DFSCTRNO) 

Refated Reading: For more information on the exit routines, see IMS Version 9: 
Customization Guide. 

i DFSYiOEO input/Output Edit Exit 

I The OTMA DFSYIOEO user exit allows a user to modify or cancel the IMS input 

I and output segment. However, it can also be used to perform the following tasks: 

I • Update the OTMA user data prefix. 

I • Override the IOPCB LTERM override name. 

I • Override the IOPCB MODNAME on input. 

I • Override the MODNAME on output, 

I When you specify a wait for write option on the user I/O exit for an OTMA 

I transaction with a sync level of none or confirm, IMSFP will wait for the log record 

I x'5937' or x'5938' to be logged and be physically on the log data set before the 

I commit confirm message (deallocate normal/abnormal) is sent out. It may take the 

I transaction longer to complete because of the wait, but the result is less I/O to the 

I log data set. 

I If the wait for write option is not specified on the user I/O exit, IMSFP will force a 

I physical write of the log record x'5937' or x'5938' to WADS or the current log data 

I set before the commit confirm message is sent out. The force physical write may 

I cause more I/O to the log data set. 
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I Using DFSYPRXO and DFSYDRUO OTIVfA Exit Routines to Determine 
i Destination 

OTMA allows transaction pipe names to be the same as IMS LTERM names or 
APPC/IMS TP names. To clarify whether a destination is for OTMA, IMS provides 
OTMA exit routines that can specify where IMS should look to resolve the 
destination names. The exit routines cannot change the actual destination name. 

I In an IMS subsystem, you can have many Destination Resolution exit routines, but 

I only a single Prerouting exit routine. 



Determining the destination for an OTMA message requires two phases. In each 
phase, an OTMA exit routine can be called: 

Phase 1 The Prerouting exit routine (DFSYPRXO) is called to determine the 

initial destination for the output. 

The exit routine can determine whether the message should be 
directed to an OTMA client or to IMS TM for processing. The exit 
routine cannot determine the final destination (because insufficient 
parameters are passed to it). 

Phase 2 The Destination Resolution exit routine (DFSYDRUO) is called to 

determine the final destination for the output. Each client can 
specify a separate Destination Resolution exit routine. 

The name of the DFSYDRUO exit is determined by the user or an 
OTMA client. Each client can have its own dedicated DFSYDRUO 
exit. 



Both of these exit routines receive control when an IMS application program issues 
an ISRT call to an alternate program communication block (PCB), or issues CHNG or 
PURG calls. But if the destination is the name of an IMS scheduler message block 
(SMB), the Destination Resolution exit routine does not receive control. Figure 29 
on page 44 illustrates the two phases of message destination determination. 
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DFSYPRXO 



R- 0 RC=4 RC=8 



input fror.. bgaty 
GOTO 
Legacy 



:rp j! no n OTMA 
GOTO 



don the input OTMA client 
is or eiient name override, 
IMS tries to locate the 
DFSYDRUO exit. 



DFSYDRUO Exit 



RC=0 RC=4 RC=S RC=12 



OTMATPiPE is 
■ocatad or created 
for output message 



GOTO Legacy 
No! recommended 
Use DFSYPRXO 
with RC=8 




Figure 29. How DFSYPRXO and DFSYDRUO Determine Message Destination 
Recommendations: 

• Because of the potential conflict with the SMB name, OTMA clients should avoid 
using a transaction pipe name as either the transaction name or the routing key. 

• DFSYPRXO and DFSYDRUO exits should be the same for the front-end and 
back-end IMS systems within a shared queues group, if the exit routines are 
different for one or more back-end IMS systems, asynchronous output might be 
sent to different destinations, depending on which back-end IMS system 
processed the input. 

To ensure prompt delivery of the output, enable OTMA on every back-end IMS 
system in the shared queues group. If a back-end IMS system does not have 
OTMA enabled, any asynchronous OTMA output that is inserted into an alternate 
PCB is simply queued and not delivered until the operator issues a /STA OTMA 
command. 

• Specifying OTMAMD=Y in the IMS PROCLIB member DFSPBxxxcan direct your 
OTMA message from the DFSYPRXO exit to a different DFSYDRUO exit without 
rerouting. 

• Specifying OTMASP=Y in the IMS PROCLIB member DFSPBxxx always creates 
a SYNC tpipe for the ALT- PCB output message. 
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Notes: 

1 . The SCD and PST addresses are available in the input parameter for both 
OTMA user exits. 

2. The address of the first segment of the output message is not passed to either 
user exit. 

Administering IMS for OTMA 

This section describes IMS administration considerations for OTMA. 

Related Reading: For more information on administering IMS, see IMS Version 9: 
'Administration Guide: Transaction Manager and IMS Version 9: Administration 
Guide: System. 

The following topics provide additional information: 

• "IMS Conversations and OTMA" 

• "MSG and OTMA Transactions" 

• "Fast Path and OTMA Transactions" on page 48 

• "IMS Restart Processing and OTMA" on page 46 

• "XRF Processing and OTMA" on page 48 

• "Queue Control Facility and OTMA" on page 47 

• "Using Shared Queues with OTMA" on page 48 

IMS Conversations and OTMA 

OTMA-to-IMS conversations are send-then-commit and are nonrecoverable. 

IMS creates a unique conversation ID for each transaction pipe that is saved in the 
Server token field in the OTMA state-data section of the message. This ID must be 
passed to IMS with ail subsequent client input for the conversation using that 
transaction pipe. 

The server-state flag is set to Conversational State in the state-data section of the 
message prefix when IMS acknowledges the transaction. This flag must be set for 
all subsequent client input during the conversation. 

OTMA supports the /EXIT command to terminate an IMS conversation. If a client 
wants to terminate the IMS conversation, it sends a message with the 
commit-confirmation flag set in the message-control information section of the 
message prefix (indicating a deallocate flow). IMS then terminates the IMS 
conversation. A deallocate flow must specify Conversational State for the 
server-state flag in the state-data section of the message prefix: it must also set the 
server token field. 

IVISC and OTMA Transactions 

You can use IMS Multiple Systems Coupling (MSG) with OTMA transactions. Ail 
IMS subsystems in the MSG network that process OTMA transactions must run 
under IMS/ESA Version 5 or later; if you are using IMS shared queues, all IMS 
subsystems in the MSG network must run under IMS/ESA Version 8 or later. MSG 
processing in an OTMA environment is similar to MSG processing in an APPC/IMS 
environment: 

• A client sends a transaction to IMS. if the transaction is defined as remote for 
that IMS system, it is sent to a remote IMS system for processing, if the 
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transaction is defined as a local transaction and performs a message switch to 
another IMS system, the switched message is sent to that remote IMS system for 
processing. 

• Output from the remote application program is returned to the originating IMS. 

• IMS recognizes that the data is OTMA data and uses the transaction pipe to 
send the data to the client. 

If the remote application inserts to an alternate PCB that is a remote destination, 
the data is not routed to an OTMA destination. The remote destination does not 
route the output message to the OTMA client, even though the message has a 
prefix, if the message is to be properly routed back to the original client, the remote 
IMS must insert to a remote transaction. That transaction (at the original IMS site) 
must then send the message to the OTMA client using an alternate PCB and a 
Prerouting exit routine. 

You can use MSG with OTMA in a shared-queues environment, as long as the MSG 
link exists in the front-end IMS subsystem that is connected to the OTMA client. 

Fast Path and OTMA Transactions 

Fast Path transactions must run as send-then-comrnit transactions. Any parameters 
with the OTMA transaction that contradict this commit mode cause the transaction 
to be rejected. Existing Fast Path application programs can run with OTMA if the 
client-entered transaction is properly defined. 

IMS Restart Processing and OTMA 

If an IMS subsystem connected to an XCF group must be restarted, IMS 
reconnects to the group during restart, but ail clients must send new client-bid 
requests to IMS. 

XRF Processing and OTIrVlA 

Recommendation: The active and alternate IMS subsystems should be in the 
same XCF group. If they are not in the same XCF group, after an XRF takeover, 
the client must connect to the new XCF group. If they are in the same XCF group, 
after an XRF takeover, the client is automatically reconnected to the XCF group. 

The active IMS joins the XCF group specifying the IMS USERVAP, name as its 
member name. The alternate IMS joins the group only after an XRF takeover, and 
connects using the same USERVAR name as the member name, if the active and 
XRF alternate subsystems are in the same XCF group, during XRF takeover, the 
new active IMS: 

• Ensures that the old IMS member is disconnected 

• Rejoins the group 

• Begins delivering any queued output destined for an OTMA client, following 
client-bid processing for that client 

IMS XRF does not track the /START OTMA and /STOP OTMA commands. The IMS 
procedures for both the active and alternate IMS should both specify 0TMA=Y in 
order to ensure that IMS automatically rejoins the XCF group during XRF takeover. 

In an XRF environment, OTMA clients are equivalent to Class 3 terminals and are 
not automatically reconnected to IMS. The clients detect that IMS has left the XCF 
group and wait for IMS (or the XRF alternate) to rejoin the group. Then the clients 
send new client-bid requests to IMS. 
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The alternate system in an XRF complex does not track when resynchronization 
has begun or the resynchronization of a particular tpipe. if IMS fails during 
resynchronization, the client should detect the IMS failure, and try to resynchronize 
with the new XRF active system. 

Queue Control Facility and OTIWIA 

The IMS Queue Control Facility (QCF) replaces Message Requeuer (MRQ). MRQ 
processes messages in the background based on criteria that you provide; 
however, it is accessible only with control statements issued in a BMP environment. 
You can access QCF both online with an ISPF interface and with control statements 
in a BMP environment. 

The IMS QCF supports QTMA messages. You can use QCF to switch between all 
supported IMS releases, or between Shared Queues and non-Shared Queues. 
TMEMBER and TPIPE are the operands for the INCLUDE and EXCLUDE control 
statements. 

ttnember A 1- to 16-character OTMA transaction member (client) name. You 
can generically specify groups of names that begin with the same 
characters by using an asterisk (*) after the characters that are the 
same. An asterisk as the first character will include or exclude ail 
QTMA transactions. 

tpipe A 1 - to 8-character QTMA transaction pipe name. You can 

generically specify groups of names that begin with the same 
characters by using an asterisk (*) after the characters that are the 
same. 

To selectively recover QTMA messages, use the INCLUDE and EXCLUDE control 
statements. The format of the INCLUDE and EXCLUDE statements with QTMA 
operands is: 
INCLUDE operandi,) 

EXCLUDE operandi,) 

operand must start in column 10 and is one of the following: 

• TMEMBER=tmember 

• TPIPE=tpipe 

Exampte: To select all OTMA messages using transaction pipe name S4A1BV6, 
specify: 

INCLUDE TMEMBER-*, 

TP!PE=S4A1BV6 

All messages with the same tmember are grouped together, and the count is 
reported by the tpipe name. 

Exampte: 

**** MESSAGES INSERTED BY DESTINATION **** 
BY OTMA DESTINATION 
TMEMBERNAME 

TPIPE1 count 

TPIPE2 count 

If a client-bid request changes the name of the current QTMA Destination 
Resolution exit routine, any transactions enqueued before IMS terminates that are 
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then reprocessed by the Message Requeuer might not use the changed exit routine 
name. Inserts to alternate PCBs use the exit routine name in the client descriptor. 

With QCF, you can identify a category of message as well as the message type. 
Table 10 describes category parameters, and the supported message types and 
keywords associated with the parameter. 



Table 10. Selecting Messages by Category Type 



Category parameter 


Description 


Supported message types 
and keywords 


DESTYPE 


Checks the destination of a 
message for a seiected 
message type 


APPC, LTERM, MSG, OTMA, 
LTRAN, RTRAN, TRANS, 
VSP 


SRCETYPE 


Checks the source of the 
message for a selected 
message type 


APPC, MSG, OTMA, VSP 


M8GTYPE 


Checks the source or 
destination of the message 
for the seiected message 
type 


APPC, LTERM, MSG, OTMA, 
VSP 



Related Reading: For more information about message selection by category in 
QCF7refeFtol'MS Queue Control Facility for z/OS: User's Guide and Reference. 

Using Shared Queues with OTIWIA 

This section describes general information about using IMS shared queues with 
OTMA. 

To ensure delivery of alternate PCB processing, enable OTMA on ail IMS systems; 
assign each IMS system in the shared queue group a unique XCF member name. 

Use the /DISPLAY TRANS ALL QCNT to view ail the OTMA transactions currently in the 
shared queue group waiting to be processed. 

As the result of a temporary shortage in the HlOP storage pool, you might receive 
message DFS1269E, which notifies you of an internal IMS failure to register a shared 
queue resource. To re-register the shared queue resource for OTMA, issue the IMS 
commands /STOP OTMA and /START OTMA. 

Related Reading: For more information on message DFS1269E, see IMS Version 
9: Diagnosis Guide and Reference and IMS Version 9: Messages and Codes, 
Volume 2. 

Related Reading: For more information on how IMS determines whether a 
message is for OTMA, see "Using DFSYPRXO and DFSYDRUO OTMA Exit 
Routines to Determine Destination" on page 43. 

OTMA Commit-Then-Send Messages 

OTMA commit-then-send (commit mode 0) messages can be processed on any 
IMS system in the shared-queues group. Program-to-program switches can also be 
run on any IMS. 
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OTMA Unsolicited Messages 

OTMA clients must connect to every IMS system in the shared queue group in 
order to receive unsolicited messages. The OTMA client connections are necessary 
because transactions that might cause unsolicited messages can run on any IMS 
within the shared-queues group. 

If the IMS that processes an unsolicited message (the backend system) is a 
different IMS than the one that receives the message, the unsolicited message is 
delivered by the back-end system. Therefore, OTMA must also be enabled on the 
backend IMS. For example, message DFS555I, which notifies you that an application 
program abend occurred during transaction processing, is an unsolicited message 
that might be delivered by the back-end system. 

OTMA Send-Then-Commit Messages 



!Vt =agt 
Queues 



Figure 30. OTMA Messages Being Processed on Munpic IMS "yiHms in a Shared-Queues 
Group 

OTMA send-then-commit messages can also be processed on any IMS system in 
the shared queue group. This is shown in Figure 30. Synchronous and 
asynchronous transactions created by a program-fo-program switch from an input 
synchronous transaction always run on the same IMS system as the transaction 
that initiated the program-to-program switch. 

In addition, program-to-program switching is not allowed for protected conversations 
{sync level 2). For more information on program-to-program switching, see "OTMA 
Program-to-Prograrn Switch Processing" on page 56. 

Synchronous transactions which use send-then-commit processing support the 
following commit levels: 

• NONE 

• CONFIRM 

• SYNCPT 

Asynchronous transactions which use commit-then-send processing support the 
following commit levels: 

• RESYNC 

• NO RESYNC 

The commit levels for synchronous and asynchronous transactions are shown in 
Figure 31 on page 50. 
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F;gure 37. Synchronous and Asynchronous Transactions and Their Respective Commit 
Levels 

All of the IMS systems in the shared queue group must be on MS Version 8 or 9, 
with z/QS Version 1 Release 2 or above, to enable the shared queue function for 
send-then-commit messages. 

Use the DBRC INIT.RECON MINVERS(81) or CHANGE. RECON MINVERS(81) command to 
ensure that all of the IMS systems are Version 8 or above. 

Use the /'DISPLAY ACTIVE command to determine whether the shared queue 
function for OTMA send-then-commit is active. 

Using Other IMS Commands 

The IMS command /DISPLAY TMEMBER member nameTPIPE tpipename QCNT shows the 
tpipe status and the output message queue count in a shared queue for a particular 
IMS system. 



OTIWIA Restrictions 

This to: 



c outlines general restrictions for the OTMA environment. 



The maximum total length of all prefixes for an OTMA message is 4096 bytes. This 
length does not include any appiication data. 



Existing IMS appiication programs that use SETO caiis might not run as e 
APPC/IMS application programs using SETO calls might require modification to use 
implicit OTMA support, 

IMS conversational and Fast Path transactions must be defined as 
send-then-commit. Existing Fast Path applications can run with OTMA. 

A transaction from an IMS terminal (for example, a SLU 2 terminal) cannot route 
output directly to a client, but must use an OTMA Prerouting exit routine 
(DFSYPRXO). 



OTMA does not support the IMS Message Format Service (MPS). However, the 
MFS message output descriptor (MOD) name can be specified by the client in the 
prefix of an OTMA message. 



OTMA does not 



IMS Front-End Switch. 
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OTMA messages cannot be encrypted. 

All user IDs must be verified by RACF, unless the client specifies no security 
checking in the security-data section of the message prefix, 

IMS modules that contain XCF macros must be reassembled for new releases of 
IMS. 

OTMA has read only access to the main storage data base (MSDB). No update 
access is available to MSDB from OTMA. 

OTMA does not operate in the IMS DBCTL environment. 

OTMA does not allow IMS terminal control commands like but not limited to 
/FORMAT, /HOLD, /RCL, and /SIGN commands. 



Managing System Resources and OTMA 

In an IMS-OTMA environment, several things can influence how IMS system 
resources are used. This section describes these system resource considerations. 

IMS Message Queue Data Set Size and OTMA 

Messages entering IMS from OTMA contain both the OTMA message prefix and 
other existing IMS message prefixes. The OTMA message prefix is variable in 
length. Excluding the user data section, the OTMA message prefix can become 
very large, sometimes over 200 bytes in length. The OTMA message prefix, 
including the user data section, is stored on IMS message queue data sets, which 
increases usage of the queue buffer pool. 

Recommendation: Because of this increase in queue buffer pool usage, try to 
increase the size of the message queue data sets. 

Buffer Pool Usage for OTMA 

If an IMS-OTMA environment has heavy OTMA traffic, a significant increase in 
LUMP and HIOP pool usage can occur. Because LUMP and HIOP pools are 
allocated from private storage, you might need to increase the size of the IMS 
control region. Also, certain OTMA control blocks are allocated from extended 
common service area (ECSA), another limited resource. 

Recommendation: Increase the ECSA size according to your workload. For 
example, if a client is sending more than 20 messages over 100 tpipes within a few 
seconds, try increasing the IMS control region size to 200MB or more, and increase 
the ECSA size to 50MB or more. If you cannot increase the IMS control region size 
or the ECSA size, try balancing your workload to allow IMS to reuse its buffers 
more effectively. 

Tpipe Number Recommendations for OTMA 

Because tpipes consume significant amounts of IMS resources and processing 
time, try to limit the number of tpipes for each tmember. 

Recommendation: Restrict the number of tpipes to 100 or less for each tmember. 
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i Tpipe Clean-Up 

I OTMA will scan its Tpipes during IMS checkpoint processing to determine whether 

I any Tpipes should be deleted. A Tpipe will be retrieved if it has been IDLE for two 

i consecutive checkpoints. To be flagged as IDLE, a Tpipe: 

I • May not process commit-then-send (CMO) messages in a shared queues 

i environment. 

i • May not have STOP declared on it. 

I • May not be the subject of a Tpipe trace. 

I • May not have any uncompleted send-then-commit (CM1) messages. 

I • May not be using a synchronous Tpipe from MQSeries. 

i • May not have queued commit-then-send (CMO) output messages. 

Dependent Region Occupancy and OTMA 

A send-then-commit transaction remains in a dependent region while the output is 
being sent (before a sync point occurs). 

Reconrsmeiidatioiis: 

• If many of your transactions are send-then-commit transactions, increase the 
number of dependent regions to improve throughput performance. 

• Use as many commit-then-send OTMA transactions as possible. 

OTIWIA Security Overhead 

You can reduce security overhead in IMS by letting the clients perform all security 
checking. If you set the no-security-checking flag in the security-data section of the 
message prefix, you can avoid much of the RACF overhead and improve IMS 
performance. 

Refated Reading: For more information on security, see "Establishing Security for 
OTMA." 



Establishing Security for OTMA 

This section describes usage information for the /SECURE OTMA command, what 
the four OTMA security levels are. and lists some general security considerations 
for OTMA. 

Using the /SECURE OTiVtA Command 

This section describes usage information for the /SECURE OTMA command. Complete 
information for how to use this command is provided in IMS Version 9; Command 
Reference. 

The client-bid request for a client includes the following: 

• The access control environment element (ACEE) 

After RACF returns an ACEE address for a verified user ID to IMS, the ACEE is 
used in a subsequent (or second) call to RACF. It is used to determine the user 
ID's authorization to the IMS command or IMS transaction requested in the input 
message. The ACEE for each user ID and the ACEE expiration value are saved 
in an OTMA table. The ACEE expiration value is specified during the client-bid 
time. If a user ID is revoked and the ACEE is not expired, you must issue /STOP 
and /START OTMA to rebuild the ACEE table, 

• The access control environment element (ACEE) aging value 
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• The client user token 

The user token is optional (except when RACF security is used) and is identified 
in the security-data section of the message prefix. 
« Add transactions or commands that must be protected to the TiMS or CIMS 
classes, respectively. If the transaction is not in the TiMS class, or the command 
is not in the CIMS class, the transaction is allowed regardless of the option you 
set with the /SECURE OTMA command. 

When you enter an OTMA command, OTMA issues a RACHECK to validate the 
command. OTMA passes only the command verb to DFSCCMDO for verification, 
not the entire CVB control block. 

• Use the IMS startup/execution parameter of OTMASE to globally specify the 
OTMA security level for all the OTMA clients. Alternately, issue the /SEC OTMA 
command to specify the security after IMS is started. However, you cannot set 
the OTMA security level for an individual OTMA client. 

If you specify /SECURE OTMA NONE, IMS does not use RACF for security verification, 
regardless of what security level is specified by the class for a client-bid request or 
i for transactions. The REFRESH option allows you to dynamically refresh cached 

I security ACEE values for user IDs of one individual OTMA member or multiple 

I OTMA members. Therefore, the only commands that can be used are the following 

default commands: 

• BRO 

• LOG 

• LOG 
« RDi 

• UNL 

Selecting an OTMA Security Level 

This section describes the five security levels common to OTMA. There are five 
OTMA security levels, but only 1 OTMA security level can be in effect at any point 
in time. The OTMA security levels are NONE, PROFILE, CHECK, FULL, and 
REFRESH: 

NONE A system-wide security level. RACF is not called for messages 

received through OTMA. Specifically: 

RACF is not called when IMS receives the connection request 
(client-bid) from WebSphere MQ or IMS Connect. 

RACF is not called to verify that the user ID in the incoming 
message is a valid user ID {one that has been defined to RACF). 

RACF is not called to verify that the user ID in the incoming 
message is authorized to the IMS command or IMS transaction 
requested in the message. 

The user ID caching scheme is not used. 

PROFILE A message-by- message security level. In other words, each 

incoming message entered through OTMA is checked to determine 
whether or not RACF will be called. IMS checks each incoming 
message independently to see if the security value is set to NONE, 
CHECK, or FULL. Specifically: 

Messages entered from IMS Connect will contain a 1-byte security 
flag field. The value in this field determines whether or not RACF is 
called. 
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CHECK 



FULL 



Messages entered from the WebSphere MQ-IMS Bridge application 
will contain a SecurityScope field in the MQIIH structure. The value 
in this field will determine whether or not RACF is called. 

Tip: Consider using the PROFILE security level for situations when 
application developers set the RACF security level as N (NONE), C 
(CHECK), or F (FULL) in each incoming message. In this case, the 
security level set in each message determines whether MS calls 
RACF for security checking related to that message. You might not 
want application programmers deciding on the security for IMS 
commands and IMS transactions, RACF is called when IMS 
receives the connection request (client-bid) from WebSphere MQ or 
IMS Connect. 

A system-wide security level, which means that RACF is called for 
messages received through OTMA. Specifically, RACF is called: 

• For client-bid connection requests. A cache, or hash table, is 
built for each OTMA client if the client-bid is successful. 

A user ID caching scheme is used in IMS/OTMA environments. 
The caching scheme also improves authorization checking 
performance. 

A cache, or hash table, is used to store previously verified user 
IDs. Each OTMA client (IMS Connect, WebSphere MQ for z/OS, 
etc.) has a hash fable created in the IMS control region after a 
successful client bid. Use of the hash table minimizes the 
number of calls to RACF to VERIFY user IDs. This way, if the 
same user ID enters multiple messages destined for IMS/OTMA, 
IMS can check the hash table for a valid entry for the user ID 
and might be able to avoid the VERIFY call to RACF. The entry 
for the user ID in the hash table contains a pointer to the ACEE 
for the user ID. The ACEE that is pointed to can be used for 
resource (command and transaction) FASTAUTH calls to RACF. 

• To VERIFY that the user ID in the incoming message is a valid 
user ID (one that has been defined to RACF). 

if the OTMA client (IMS Connect or WebSphere MQ for z/OS) 
supplied a UTOKEN in the incoming message, IMS supplies the 
address of the UTOKEN on the VERIFY call to RACF. Use of the 
UTOKEN in VERIFY processing improves performance. RACF 
returns an ACEE security control block to IMS for verified user 
IDs. 

• To verify that the user ID in the incoming message is authorized 
to the IMS command or IMS transaction requested in the 
message. The address of the ACEE, previously built by RACF 
during verify authorization processing, is supplied by IMS on the 
FASTAUTH call to RACF. 

• To verify that the user ID in the incoming message is authorized 
to the IMS transaction code set as the destination on a DL/I 
CHNG or AUTH call. However, an existing ACEE is not used for 
these calls; therefore, another call is made to RACF to 
dynamically build an ACEE for the CHNG or AUTH call, if you 
know the application will issue many CHNG or AUTH calls, 
consider using a different OTMA security level to overcome the 
performance impact. 

A system-wide security level, which means that RACF will be called 
for messages received through OTMA. 
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FULL has the same characteristics as CHECK, with two exceptions: 

• During the verify processing, RACF is called a second time to 
build an additional ACEE security control block in the dependent 
region. 

• If the application program that processes the OTMA-entered 
transaction issues one or more CHNG calls (or AUTH calls with 
the destination set to a different transaction code), the security 
environment already exists in the dependent region and does not 
have to be dynamically built. Alternately, if the application does 
not issue these calls, a security level of FULL is not needed, and 
you might consider an OTMA security level of CHECK or 
PROFILE. 

Reiated Reading: For more information on IMS security, see IMS Version 9: 
Administration Guide: System. 

For more information on the values NONE, FULL, or CHECK, see the /SEC OTMA 
command in IMS Version 9: Command Reference. 



General OTMA Security Considerations 

• if you use RACF (or an equivalent product) for security, define the 
IMSXCF.group.client_member_name in the FACILITY class. 

if you define the IMSXCF. group. cl ient_member_name in the FACILITY class, and if 
IMS security is not set to NONE, the user token for the client-bid request must be 
valid and the user must have READ access to the FACILITY class. 
If the user token for a client-bid request fails RACF verification, the client 
receives a NAK message from the server. 

• Authorize the XCF client for z/OS. 

• if you define your OTMA applications with full security, the security environment 
is kept until the application ends. 

• After IMS receives messages received from OTMA, when OTMA security is 
activated, IMS calls RACF to verity that the user ID in the incoming message is a 
valid RACF user ID. IMS is not passed a password for the user ID, so the call to 
RACF is to verify the user ID only, if the users password has not been validated 
before IMS receives the message, the password cannot be validated. 

• IMS uses the UTOKEN in the input message in the call to RACF not only to 
verify the user ID, but also to create a security control block in the IMS control 
region to represent each verified user ID. The security control blocks built in the 
IMS control region, representing verified RACF user IDs, are called accessor 
control elements or ACEEs. 



Using DM Calls In an OTMA Environment 

This section describes the DL/i calls that are used in an OTMA environment: 

CHNG if a CHNG call is issued from an OTMA submitted transaction, the destination 
is assumed to be the same OTMA client (the tpipe name is set by the CHNG 
call). This behavior can be altered by the OTMA Prerouting and Destination 
Resolution exit routines. 

An IMS application program that issues a CHNG call to an alternate PCB 
(specifying an options list) does not cause IMS to call the OTMA Prerouting 
and Destination Resolution exit routines to determine the destination. 
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However, an IMS application program that issues a CHNG cali to an alternate 
PCB (specifying an APPC descriptor) does cause IMS to call the OTMA exit 
routines to determine the destination. 

The application program can still issue ISRT calls to the I/O PCB to send 
data to an OTMA destination. 

OTMA application programs can use CHNG and ISRT calls for APPC 
destinations, 

INQY {null} 

An INQY call issued for an OTMA destination returns the following 
information: the transaction pipe name, the client XCF member name, the 
user ID, the group name, and the synchronization levels. 

PURG An IMS application program that issues a PURG call causes IMS to call the 
OTMA Prerouting and the Destination Resolution exit routines to determine 
the destination. 

SETO An IMS application program that issues a SETO call does not cause IMS to 
call the OTMA Prerouting and the Destination Resolution exit routines to 
determine the destination. 

Existing IMS application programs that issue SETO calls might not run as 
expected because a return code is returned to the program if it is 
processing an OTMA-originated transaction. APPC/IMS application 
programs that issue SETO calls might need modification if they require 
implicit OTMA support. 

One way to make these application programs work is to use an INQY call 
before issuing the SETO call. The application program can use the output 
from the INQY call to determine if a transaction originated from an OTMA 
client, and not issue the SETO cali. 

For those DL/I calls that cause IMS to cali one of the OTMA exit routines, IMS only 
calls the exit routines if the destination has not yet been set (for example, by 
another DL/i call). 

Refated Reading: For more information on these calls, see IMS Version 9: 
Application Programming: Transaction Manager. 

To initiate protected conversations (such as accessing multiple resource managers' 
resources under one unit of recovery in an RRS/MVS environment), the 
client-adapter code (OTMA user) must acquire and own a private context and 
provide the context ID in the state-data section of the message prefix. 

Definition: A context is a z/OS entity under which resource managers perform 
work; a private context is required in this environment. 

During message traffic between IMS and the client, if the context-ID field in the 
message header is non-zero, protected conversation processing occurs. 



OTMA Program-to-Program Switch Processing 

This section describes how OTMA program-to-program (P2P) message switches 
occur. Two types of message switch occur in OTMA: commit-then-send, and 
send-then-commit. Each type is described briefly below. This section focuses 
primarily on the send-then-commit message switch and provides usage scenarios 
for different send-then-commit message switches. 
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For OTMA commit-then-send input messages (also called asynchronous or CMO 
messages), the program switch always results in another CMO message. For OTMA 
send-then-commit input messages (also called synchronous or CM1 messages), the 
program switch results vary, depending on whether: 
« there is an ISRT call to the I/O PCB 

• an express PCB is used for the switch 

• there is a switch to multiple programs 

• the IMS start-up parameter OTMAASY=Y is specified 

• the transaction is protected 

A P2P switch for a CM1 input message, therefore, could be another CM1 message, 
a DFS2082 message, or a CMO message. In addition, some OTMA clients, for 
example WebSphere MQ, can accept a CMO output message for a CM1 input 
message; others, however, may not. 

The usage scenarios that follow apply only to send-then-commit messages. 

The following topics provide additional information: 
« "OTMA Single-Stream Program Switch" 

• "OTMA Program Switch without ISRT to I/O PCB" on page 58 

• "OTMA Program Switch with Express PCB" on page 58 

• "OTMA Program Switch to Multiple Programs" on page 58 

« "OTMA Program Switch with OTMAASY Option" on page 59 
« "OTMA Program Switch for Protected Transactions" on page 59 

• "Other OTMA Program Switch Considerations" on page 59 

GTfVfA Single-Stream Program Switch 

This basic switch is shown in Figure 32. Program A switches to program B, and 
Program B switches to Program C, which then inserts back to the I/O PCB. This 
model of program flow delivers the send-then-commit output message successfully. 
Single-stream means that the program switches occur one after another. No 
express PCBs are used in the P2P message switches. 



send-then-commit 



send-then-commii 



| switch to 



Figure 32. Single-Stream Program Switch 
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OTMA Program Switch without 1SRT to I/O PCB 

When several switches occur in sequence and none inserts back to the I/O PCB, 
message DFS2082 is sent back to the OTMA client. The last program switched to, 
Program C, does not insert back to the i/O PCB. IMS therefore generates message 
DFS2082 for the OTMA client. 

Attention: if program C runs in a remote IMS through MSG and the program 
does not insert back to the I/O PCB, the remote IMS does not issue message 
DFS2082. However, in this case, the OTMA client program might hang and the 
front-end IMS control region will experience a build up of its control blocks. This 
kind of build up could result in a storage- related system outage. Restarting IMS 
releases the control blocks. 

GT1V1A Program Switch with Express PCB 

A P2P message switch with an express PCB can lead to a eommit-then-send output 
message. Program A uses an express PCB rather than a non-express PCB to 
perform the P2P message switch. The output from Program B is commit-ihen-send 
because using the express PCB forces Program B to be processed asynchronously. 
When a program is processed asynchronously and inserts back to the I/O PCB, the 
output message is sent as a comm it-then-send message. However, if Program A 
also switches to Program C using a non-express PCB, Program C then inserts back 
to the I/O PCB. The output from C will be a send-then-commit message. 

OTIWIA Program Switch to Multiple Programs 

After a program inserts back to the I/O PCB, the rest of the P2P message switch, if 
any, is processed asynchronously. Program A switches to Program B, which inserts 
back to the I/O PCB. The output from Program B will be a send-then-commit 
message. Program B then switches to program C, which will be processed 
asynchronously. 

A "race" condition can occur when a program switches to multiple programs. 
Program A switches to multiple programs using non-express PCBs. Only one 
switched-to program, the one scheduled first, is processed synchronously. The rest 
of the switched-to programs are processed asynchronously. If the program 
processed synchronously inserts back to the I/O PCB, the output message is a 
send-then-commit message. 

In some cases, one of the multiple programs could be a remote program. This 
program flow is shown in Figure 33 on page 59. Program A switches to remote 
Program B through MSG. Program B first launches a new program, Program C, in 
the local IMS and then inserts a response to the OTMA client through the local IMS. 
Depending on what happens first (scheduling of Program C or the processing of the 
response for the OTMA client) in the local IMS, an unwanted DFS2082 message 
could be sent to the client. This is also a race condition. If Program C gets 
processed first in the local IMS, a DFS2082 message is sent. If the response is 
processed first, the expected output from Program B is delivered synchronously 
using send-then-commit. 
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Figure 33. Race condition resulting from program switch to multiple programs 

To avoid creating the race condition in these circumstances, you can do any one of 
the following: 

• Modify your programs to avoid multiple program-to-program switches within the 
same transaction for send -then-commit (CM1). 

• Use commit-then-send (CMO) input when performing multiple program-to-program 
switches within the same transaction. 

• Use the IMS start-up parameter OTMAASY to serialize P2P message switch 
processing, described in "OTMA Program Switch with OTMAASY Option." 



OTMA Program Switch with OTMAASY Option 

The IMS start-up parameter OTMAASY can be used to serialize P2P message 
switch processing to prevent a potential race condition. To avoid the race condition 
OTMAASY is used to create a program switch model similar to the single-stream 
model. Program B, for which the response mode transaction is processed 
synchronously, can deliver the send-then-commit {synchronous} output message. 
Program C, which is running with a non-response mode transaction, processes the 
I message asynchronously. With this method, the race condition described in "OTMA 

i Program Switch to Multiple Programs" on page 58 can be avoided. 

OTIVtA Program Switch for Protected Transactions 

For a non-conversational program that performs a P2P message switch for a 
protected transaction, ABENDU0711, with reason code 1D, will be returned. For a 
conversational program, the program receives an X6 status code. 

Other OTMA Program Switch Considerations 

The following considerations also apply to P2P switching: 
« The P2P message switch is not supported for OTMA protected messages 
(send-then-commit input with syncievel = SyncPt). 
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• If a non-conversational program performs a P2P message switch to a program in 
a Shared Queues environment, the program in the SQ environment must be 
running on the same IMS where the first program gets scheduled. 



MS Commands Using OTMA 

OTMA clients can enter IMS commands. 

Restrictions: OTMA clients cannot enter IMS commands from the following: 

• An IMS Remote Site Recovery (RSR) tracking subsystem 

• An IMS Extended Recovery Facility (XRF) alternate subsystem 

• A CICS-IMS DBCTL subsystem 

Only certain commands are valid from OTMA. 

Related Reading: For more information on supported IMS commands, see IMS 
Version 9: Command Reference. 

OTMA Terminology 

The following terms apply to this section : 

tpipe is analogous to an LTERM. it is a logical structure that represents 

an anchor point for client transactions and output. The tpipe name 
is unique within a client structure. 

tmember is the name of a client that connects to an OTMA group. The group 
is created by the first member to join it, usually IMS. All members 
are clients, except IMS, which is the server. Clients communicate 
with IMS using the XCF interface by sending transactions to IMS, 
IMS then returns the output to those clients. 

OTMA Represents the logical collection of ail XCF members associated 

with a given group name. 

The initial letter "T" in tpipe and tmember represents "Transaction." 

Modified Commands for OTMA 

The following commands have been modified for OTMA. 

• /DISPLAY ACTIVE 

This command displays OTMA group status. Only one OTMA group can be 
active at a time. 

• /DISPLAY OTMA 

This command displays the following information for OTMA clients and servers: 

- Each member in the XCF group 

- The XCF status for each member 

- The user status for each member 

- The security status for each server 

If the IMS application program uses the alternate PCB, the exit routine 
determines the destination, and the member name is displayed, even when it is 
not in the same group. The status can be either active or not defined. 
After the client-bid request is received from a tmember, IMS creates a tmember 
control block for that tmember. if the command is issued prior to the client-bid 
request, the tmember is not displayed. 
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/DISPLAY SHUTDOWN STATUS 

This command displays shutdown status of OTMA processing. The following 
OTMA information is displayed: 

- The current phase of OTMA shutdown processing 

- Whether the transaction is commit-then-send or send-then-commit 

- Which clients and transaction pipes are in progress and thus preventing 
shutdown from completing 

/DISPLAY STATUS TMEMBER 

This command displays all transaction pipes that are stopped. 
/DISPLAY TMEMBER ALL 

This command displays the following information for OTMA clients and servers: 

- Each member in the XCF group 

- The XCF status for each member 

- The user status for each member 

- The security status for each server 
/DISPLAY TMEMBER QCNT 

This command displays the number of asynchronous output messages on the 
global queue for the specified OTMA member. The QCNT keyword is valid only in 
a shared-queues environment. 

/DISPLAY TMEMBER tmembername TPIPE tpipename \ ALL 

This command displays tpipe status for each tmember, including: 

- Enqueue and dequeue counts 

- Current queue count 

- Current status 

The ENQ/DEQ counts on a TPIPE are only updated for commit-then-send (CMO) 

output messages. ENQ/DEQ counts are never updated for send-then-commit 

(CM1) regardless of the sync level, because CMO messages are recoverable and 

CM1 messages are non-recoverable. 

/DISPLAY TMEMBER tmembername QCNT TPIPE tpipename 

This command displays the number of asynchronous output messages on the 

global queue for the specified OTMA member and transaction pipe. The QCNT 

keyword is valid only in a shared-queues environment. 

/DISPLAY TRACE TMEMBER 

This command displays all the transaction pipes that are currently being traced 
for the specified client. 
/DISPLAY TRANSACTION 

This command, when issued by an OTMA client, sends its output directly to the 
client, not to the IMS master terminal. Depending on the setting of the 
extended-response-requested flag in the message-control information section of 
the message prefix, the output is either in an architected format {only supported 
for this command) or in the standard IMS format. 
Related Reading: 

- For more information on the message prefix, see Chapter 5, "OTMA Message 
Prefix," on page 71 . 

- For information on the transaction attributes provided in the application-data 
area, see Chapters, "OTMA Architected Transaction Attributes," on page 97. 

/DEQUEUE TMEMBER TPIPE 
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This command dequeues messages from the transaction -pipe structure 
associated with the transaction pipe. 
/SECURE OTMA 

This command is used to control the RACF security level for OTMA 
client-originated transactions. You can specify that RACF be used or bypassed. If 
RACF is bypassed and NONE is specified, you can issue only the foliowing 
default unsecured commands: 

- BRO 

- LOG 

- LOG 

- RDI 

- UNL 

You can also use the PROFILE keyword to specify or bypass RACF security for 
individual transactions. This can be important if you do not want the performance 
overhead of processing security for your entire transaction workload. You specify 
the security for each transaction by setting the values in the security-data section 
of the OTMA message prefix. 

The /'DISPLAY OTMA command shows the security option currently in effect. 
/START OTMA 

This command causes IMS to join the XCF group (and create the group if 
necessary). All clients must know the group name, which is specified on the 
GRNAME= parameter in the IMS PROCLIB member DFSPBxxx The XCF group is 
created and joined according to the following rules: 

- in the IMS procedure, if 0TMA=N and GRNAME= is set to blanks, the XCF group 
can be neither created nor joined. 

- if 0TMA=N and GRNAME= is set to a valid value, the XCF group is created and 
joined when you issue the /START OTMA command. 

-- if 0TMA=Y, the XCF group is both created and joined as part of IMS 

initialization, in this case, the /START OTMA command is used to rejoin a group 
after a /STOP OTMA command has caused IMS to leave the group. 

It is assumed that all clients know the names of the servers with which they are 

to communicate. 

/START OTMA initiates the following processing: 

1 . IMS joins the XCF group. 

2. After a successful client-bid request, IMS sends an ACK message to the 
client. 

3. IMS begins sending ail commit-then-send output to the client. 
/STOP OTMA 

This command causes IMS to leave the XCF group (but it does not stop the 
group itself). All clients must know the group name, which is specified on the 
GRNANE= parameter in the IMS procedure. 
/START TMEMBER tmembername TPIPE tpipename j ALL 

This command causes IMS to send one of the following OTMA commands to the 
client: 

- "resume input for tpipename" 

- "resume input for all tpipenames" 

IMS then resumes sending output to the client. 
/STOP TMEMBER tmembername TPIPE tpipename j ALL 

This command causes IMS to send one of the following OTMA commands to the 
client: 
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- "suspend input for ipipename" 

•-- "suspend input for all tpipenames" 

IMS then does not send any more output to the client. 

• /TRACE SET ON j OFF TABLE OTMT 

This command starts or stops online tracing to the OTMA trace table (OTMT). 

• /TRACE SET ON j OFF TMEMBER TPIPE 

This command starts or stops online tracing of OTMA client activity and 
transaction-pipe activity for clients. 

A temporary fpipe is created when you issue a /TRACE tpipe or /STOP tpipe 
command against a tpipe that does not exist. A temporary tpipe is converted to a 
permanent tpipe if an input message reaches IMS through the tpipe or if an 
output message is queued to the output queue of the tpipe. 
When you issue a /DISPLAY tpipe command against a temporary tpipe, the 
status of TMP is displayed. 

Generally, an OTMA client should use the send-then-commit flow to process IMS 
commands. However, to process any of the following commands, the client must 
use the commit-then-send flow: 
» /DBDUMP DATABASE 

• /DBRECOVERY AREA j DATABASE 

• /START AREA | DATABASE 

• /START REGION 

• /STOP AREA j DATABASE 
» /STOP REGION 

Recommendation: Because the client must use the commit-then-send flow, the 
output from these commands cannot be tied to the input command. The OTMA 
prefixes are not replicated (the only field common to both the input and the output is 
the transaction -pipe name). Therefore, it is recommended that the client submit IMS 
commands using a transaction pipe that the client reserves for IMS command 
processing. 



The IMS messages (DFSnnnn) that are introduced by OTMA are listed in Table 11 

Related Reading: For more information on these messages, see IMS Version 9: 
Messages arid Codes, Volume 2, 

Table 11. IMS Messages introduced by OTMA 



MS Messages introduced by GTfVfA 



DFS1268 

DFS1283E 

DFS1288E 

DFS1293E 

DFS2224 

DFS2384! 

DFS2371! 

DFS2376W 

DFS2391I 

DFS239S! 



DFS1269E 
DFS1284E 
DFS1289E 
DFS1294E 
DFS2360! 
DFS2365! 
DFS2372! 
DFS2384E 
DFS2392I 



DFS1280E 
DFS1285E 
DFS1290E 
DFS1295E 
DFS2361I 
DFS2368S 
DFS2373S 
DFS2385E 
DFS2393S 



DFS1281E 

DFS1286E 

DFS1291E 

DFS1296E 

DFS2362! 

DFS2369I 

DFS2374W 

DFS2389I 

DFS2394I 



DFS1282E 

DFS1287E 

DFS1292E 

DFS1297E 

DFS23S3! 

DFS2370I 

DFS2375W 

DFS2390I 

DFS2395I 
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In addition, messages DFS3657 and DFS3659X are modified for OTMA to include 
the 16-byte descriptor name. 
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This chapter provides diagnostic information for OTMA. 

The following topics provide additional information: 

• "OTMA Sense Codes for NAK Messages" 

* "OTMA Return Codes" on page 69 



GTfVf A Sense Codes for NAK Messages 

This section lists the sense codes that accompany OTMA negative 
acknowledgement (NAK) messages. Codes X'0000' through X'OFFF' and X'9000 1 
through X'FFFF' are reserved for IBM use. Codes X ! 1Q0Cr through X'BFFF' are 
reserved for customer use. 



0001 

Explanation: IMS received a message from a client, 
but the message is not part of the OTMA signon 
protocol. The client is not yet ready for message 
processing. 

Programmer response: Make sure that the client has 
sent the client-bid request and successfully received an 
ACK for that client-bid request. 



0002 

Explanation: IMS received a message from a client, 
but the client cannot send or receive messages. 

Programmer response: Make sure that the client is 
not stopped. 



0003 

Explanation: Either the client-bid request did not 
correctly set the length of the state-data section, or the 
application-data section is present. 

Programmer response: Make sure that the length of 
the state-data section and the XCF length fields are 
correct. The application-data section should not be 
included in the client-bid request. 



0004 

Explanation: Reserved 



0005 

Explanation: IMS received a message for a 
multi-segment message that duplicated an existing 
segment. 

Programmer response: Make sure that the segment 
number is not duplicated. 



0006 

Explanation: IMS received a return code from XCF 
after attempting to receive the message. The return 
code is saved in the reason code field of the 
message-control information section of the message 
prefix. 

Programmer response: Refer to the appropriate z/OS 
programming manual for action. 



0007 

Explanation: The maximum number (255) of clients 
was reached. No new client structure is created. 

Programmer response: Make sure the client name is 
correct and that you have not exceeded the limit of 255 
clients. 



0008 

Explanation; The security check by IMS rejected the 
client-bid request. 

Programmer response: Make sure the security data 
specified in the client-bid request is valid and correct. In 
addition, verify RACF definitions and the IMS security 
exit routine. 



0009 

Explanation: IMS received an invalid OTMA 
command. 

Programmer response: verify the OTMA command. 
For a list of allowable commands, see "OTMA 
Message-Control Information" on page 71. 



000A 

Explanation: IMS received an OTMA data message. 
IMS only accepts transaction, command, response, or 
commit messages. A data message must be a 
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continuation of an s MS conversational transaction. 

Programmer response: Verify the data message 
being sent. The data flag in byte 1 of the OTMA controi 
data could have been set incorrectly, or the 
conversation Iteration message was sent to a 
terminated IMS conversational transaction. 



000B 

Explanation: IMS received an Invalid message type. 
An OTMA message must be a transaction, command, 
response, data, or commit message. 

Programmer response: Make sure the Message Type 
in the message-control information section of the 
message prefix is set properly. 



oooc 

Explanation: Reserved 



GOOD 

Explanation: IMS received an OTMA data message 
for continuation of an IMS conversation using a 
nonexistent transaction pipe. 

Programmer response: Make sure the transaction 
pipe exists and that the first iteration of the IMS 
conversation Is successfully completed. 



000E 

Explanation: IMS was unable to create the transaction 
pipe to process the message. 

The synchronized tplpe flag in the processing flag of the 
OTMA message-control-information prefix was set 
incorrectly on or off an existing tplpe. After a tpipe is 
created for an input or output OTMA message, the 
synchronized tplpe setting for the tplpe cannot be 
changed for the subsequent input or output OTMA 
message. 

Programmer response: Make sure IMS storage pools 
are properly allocated and available. 



000F 

Explanation: The transaction pipe for the message 
was stopped. 

Programmer response: Find out why the transaction 
pipe was stopped. Issue an IMS /START command to 
restart the transaction pipe. 



0010 

Explanation: The OTMA message had no state data. 

Programmer response: Verify that the state-data flag 
is set and that state data is present. 



0011 

Explanation: IMS received the OTMA commit 
message, but the request was not to terminate the 
conversation. IMS only allows commlt-type messages 
for terminating IMS conversations (equivalent to the IMS 
/EXIT command). 

Programmer response: Make sure the commit 
message is used to terminate an IMS conversation. 



0012 

Explanation: The OTMA message prefix was too 
large. The maximum size of the OTMA prefix is 4 KB. 

Programmer response: Check the size of the OTMA 
message prefix. 



0013 

Expianation: The client-bid request did not set the 
size of the message hash table. This size is a required 
field, which is to be set by the client for client-bid 
requests. 

Programmer response: Set the message hash table 
size in the client-bid request. 



0014 

Explanation: The client sent a second client-bid 
request while the first client-bid request was still active. 

Programmer response: Make sure the client leaves 
and joins the XCF group before sending a new 
client-bid request to IMS. 



0015 

Expianation: IMS was unable to allocate storage for 
the message hash table. 

Programmer response: Check the specified size of 
the message hash table: it might be too large. 



0018 

Explanation: Client was not yet active and ready for 
message processing. 

Programmer response: Make sure the client-bid 
request was sent and successfully completed. Also 
check that the XCF state is active. 



0017 

Explanation: The OTMA message specified an invalid 
synchronization level in the state-data section of the 
message prefix. The synchronization-level field should 
be either None, Commit, or SYNCPT. 

Programmer response: Make sure the 
synchronization level is valid. 
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0018 

Explanation: The OTMA message had an invalid 
transaction-pipe name. See "OTMA Naming 
Conventions" on page 14 for the naming ruies for 
transaction pipes. 

Programmer response: Correct the transaction-pipe 
name. 



0019 

Explanation: The OTMA message had an invalid 
client name. See "OTMA Naming Conventions" on page 
14 for the naming ruies for ciients. 

Programmer response: Correct the client name. 



001 A 

Explanation: IMS detected an error and canceled the 
message before putting it on the iMS queue for 
processing. Usually, an IMS message (accompanying 
the NAK) describes the problem. 

Programmer response: See the reason code that 
accompanies the NAK code. 

Table 12 lists the reason codes. 



Table 12. Fleason codes associated with the 001 A 
sense code 



Hex: 


Decimal: Explanation: 


X'03' 


03 


RACF RACR0UTE VERIFY call failed for 
incorrect input userid. 


X'15' 


21 


The message segment length or ZZ 
field cannot be changed by 
DFSNPRTQ exit. 


X'16' 


22 


Invalid security option specified in the 
message prefix. 


X'17' 


23 


Invalid command from an OTMA client. 
See DFS1285E. 


X'18' 


24 


Transaction currently not available for 
use. See OFS3470E. 


X'19 1 


25 


SMB transaction/LTERM Is stopped. 
See DFS065. 


X'1A' 


28 


Invalid CPIC transaction. See 
DFS1286E. 


X'lB' 


27 


Invalid remote destination (RCNT). See 
DFS1287E. 


X'1C 


28 


Invalid CNT name specified. See 
DFS1288E. 


X'1D ! 


29 


SMB not found. See DFS064. 


X'lE' 


30 


Invalid security. See DFS1292E. 



X'l F ! 31 System error requested. 



Table 12, Reason codes associated with the 001 A 



sense code 


(continued) 


Hex: Decimal: Explanation: 


X'21' 33 


User error message. 


X'22' 34 


Single-segment message. See 




DFS1290E. 


X'23' 35 


Ail messages discarded. See DFS249. 



Null segment sent. See DFS249. One 
cause for this error maybe the length 
specified on the MSGLEN key 
parameter of the IXCMSGO macro 
does not match the length of the 
OTMA data. No extra or null data can 
be padded at the end of the application 
data section. 

X'25' 37 Queue overflow as unsuccessful insert. 

X'26' 38 Commit mode 0 not allowed for IMS 

conversational or Fast Path 
transaction. See DFS1291E. 

X'27' 39 IMS conversation is stooped, similar to 

an / EXIT command. 

X'28' 40 1 SNP4I' ieq.«s'e<. 'ha a r^saoe 

be rerouted to a remote system, out 
failed. See DFS064. 

X'29' 41 DFSNPRTO requested that a messaae 

be rerouted to a remote sysrem. out 
t -6 Soe i-^O 

X'32' 50 1 he lenarh specifiea in tne application 

data section or the segment iengtn for 
muiti-segment incut data exceeds the 
engih < >et if o the f 1SCL_^ ^cy 
parameter of the XCF IXCMSGO 
macro. 



001 B 

Explanation: IMS rejected the message, because IMS 
is shut down. 

Programmer response: Resend the message when 
IMS Is restarted. 



001 c 

Explanation: IMS rejected the message, because the 
synchronization flag was not set In the state-data 
section of the message prefix. 

Programmer response: Set the synchronization flag 
before sending the message to IMS. 



X'20' 32 System error message. 
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001 D 

Explanation: IMS rejected the message, because the 
length of the user-data section of the message prefix 
exceeded the maximum allowable length (1024 bytes). 

Programmer response: Check the length of the 
user-data section of the message prefix. 



001 E 

Explanation: IMS rejected the message, because the 
length of the server user data in the state-data section 
of the message prefix exceeded the maximum allowable 
length (256 bytes). 

Programmer response: Check the length of the 
server user data. 



001 F 

Explanation: IMS rejected the message, because the 
recoverable sequence number in the message-control 
information section of the message prefix does not 
match the IMS sequence number for the synchronized 
transaction pipe. 

if IMS receives 001 F from a client, IMS stops the tplpe. 

Programmer response: Check the recoverable 
sequence number in the message and ensure it is at 
least one greater than the current recoverable sequence 
number for the synchronized transaction pipe. 



0020 

Explanation: IMS rejected the message, because the 
message did not have any application data. 

Programmer response: Check the application-data 
section of the message prefix and ensure It has a 
transaction code or a valid IMS command. 



0021 

Explanation: IMS rejected the message, because the 
chain flag was not set in the message-control 
information section of the message prefix. 

Programmer response: Ensure the chain flag is set 
properly. 



0022 

Explanation: IMS was unable to find the transaction 
pipe associated with the Server token to process the 
conversational message. 

Programmer response: Ensure that the Server token 
is passed correctly to the server with the conversational 
state bit on. 



0023 

Explanation: The input recoverable sequence number 
is invalid. 

Programmer response: if one of the following 
conditions exists, IMS sends this NAK message in 
response to the input message: 
« The tplpe is synchronized, the transaction Is defined 

as recoverable, and the Input recoverable sequence 

number is 0. 

« The tpipe is synchronized, the transaction Is defined 
as irrecoverable, and the input recoverable sequence 
number is not 0. 

• The tpipe is not synchronized, and the Input 
recoverable sequence number is not 0. 

• The tpipe is synchronized for command input, the 
commit mode is 0, and the Input recoverable 
sequence number is not 0. 



0024 

Explanation: A conversational program has not yet 
responded to the last input message. Multiple 
conversational messages were received by OTMA; 
subsequent messages were rejected because the first 
message is still being processed. IMS discards 
subsequent messages, and responds to the accepted 
input message. 

Programmer response: Modify the client program to 
wait for the conversational transaction output before 
sending the next input message. 



0025 

Explanation: IMS has detected a resynchronization 
protocol violation during the resynchronization process. 

Programmer response: if one of the following 
conditions exists, IMS sends this NAK message in 
response to the input message: 

• The client's resynchronization logic does not follow 
the OTMA resynchronization protocol. 

• The client's message prefix specifies the Incorrect 
tpipe name or member name. 



0026 

Explanation: During resynchronization, IMS tried to 
dequeue messages without success. 

Programmer response: Contact your IBM Support 
Center for assistance. 



0027 

Explanation: During resynchronization, IMS tried to 
reset recoverable sequence numbers without success. 
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Programmer response: Contact your IBM Support 
Center for assistance. 



002E 



Explanation: The OTMA message specified an invalid 
commit mode with a synchronized tpipe in the 
state-data section of the message prefix. You must use 
the Commit-then-Serid commit mode. 



002C 



Explanation: The OTMA message prefix indicated an 
incompatibility between the sync level field and the 
context ID field, the context_id field must only be 
supplied with a sync level of SYNCPT. 



Programmer response: Correct the Incompatibility 
the message prefix. 



Programmer response: Make sure that you choose 
the Comrnit-then-Send commit mode. 



002F 



002D 



Explanation: IMS was unable to express unprotected 
interest In the context contained in the contextjd field 
of the OTMA message prefix. 



Explanation: An incompatibility between the 
synchronization level and the commit level was 
indicated In the message prefix. A send-then-commit 
level is required with a sync level of SYNCPT. 



Programmer response: Contact your IBM Support 
Center for assistance. 



Programmer response: Correct the incompatibility in 
the message prefix. 



GTIVf A Return Codes 



if an error occurs in an IMS OTMA exit routine, the IMS application program can 
retrieve a status code for the IMS call. The X'S'/DQ' records are written to the IMS 
log, and the return codes include the following: 

Code: Explanation: 

X'1C An internal interface error occurred. 

X'20' DFSYDRUO overrides exceed the maximum limit. 

X'24' DFSYDRUO specifies an invalid destination. 

X'28' DFSYDRUO specifies an invalid return code. 

X'2C DFSYPRXO returned an invalid XCF member name. 

X'30' DFSYPRXO required an XCF member name that was not returned. 

X'34' DFSYPRXO returned an invalid return code. 

X'38' The destination is in a different client, and the XCF member name from 
DFSYDRUO is invalid, 

X'3C DFSYDRUO returned an invalid user data length. 
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Chapter 5, OTMA Message Prefix 



This chapter describes the syntax of OTMA messages. OTMA messages are 
mapped by the DFSYMSG DSECT in IMS.ADFSMAC. The maximum length for a 
message prefix is 4098 bytes; this length does not include the application data. 

Table 13 shows the segments of the OTMA message prefix and lists the locations of 
some of the key fields within those prefix segments, in this table, the term "Server" 
refers to IMS. 



Table 13, OTMA Message Prefix segments and their Key Fields 



Message Control 
information 


State Data 


Security Data 


User Data 


Application 
Data 


Tpipe name 
Message type 
Sequence numbers 
Processing flag 
Response Indicator 
Chaining Indicator 


Destination 
override 
Map name 
Sync Flags 
Syncjevei 
Commit Mode 
Tokens 
Server State 


User ID 
Utoken 

Security Flags 







I The following topics provide additional information: 

i • "OTMA Message-Control information" 

I « "OTMA State Data" on page 82 

I « "OTMA Security Data" on page 91 

I • "OTMA User Data" on page 93 

I • "OTMA Application Data" on page 94 

i • "Sample OTMA Messages" on page 94 



OTfVfA Message-Control Information 

For every message, you must provide message-control information on the 
MSGCNTL parameter of the XCF IXCMSGO macro. 

Format of OTMA Message-Control Information 

Table 14 is a summary of the content of the message-control information section of 
the message prefix (column 1 from Table 13). The summary includes byte, length, 
content, hexadecimal value, the meaning, and includes usage comments. More 
information about the content follows the table in "Explanation of OTMA 
Message-Control Information Fields" on page 75. 



Table 14. Message-Control Information Summary 



Byte 


Length Content 


Vaiue 


Meaning 


Comments 


0 


1 Architecture Level 


x'or 


OTMA release level. 


Mandatory for all messages. 


1 


1 Message Type 






Mandatory for all messages. 




Data 


X'80' 


Server output data 
(output from an IMS 
application program). 


This data Is not a transaction. 
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Table 14. Message-Control Information Summary (continued) 



Byte 


Length Content 


Value 


Meaning 


Comments 




Transaction 


X'40' 


Transaction or IMS 
command input to the 
server. 


The actual transaction name Is 
specified in the application-data 
section of the prefix. 




Response 


X'20' 


A response message. 






Command 


X'10' 


An OTMA command 
(not an iMS 
command). 






Commit Confirmation 




Commit complete. 


Used oy tne serve! to notify the 
; lent of svnr po t compktio ■> 
Oniy used for send-then-eommit 
transactions. See 
"comrnit-confirmation flag below. 


2 


1 Response flag 






Response flags are mutually 
exclusive. 




ACK 


X'80' 


Positive 

acknowledgement. 






NAK 


X'40' 


Negative 

acknowledgement. 


A NAK can be accompanied by 
an additional sense code. 




Response Requested 


X'20' 


A response is 
requested for this 
message. 






Extended Response 
Requested 




Requests architected 
transaction or 
command attributes 
to be returned to the 
client. 




3 


1 Co mm it- 
confirmation flag 










Committed 


X'80' 


Server committed 
successfully. 






Aborted 


X'40' 


Server aborted 
commit. 






1 Command Type 










Client-Bid 




Sent by a client to the 
server. 


1 ne response-requested rlag 
and the appropriate state data 
fields (for example, Member Name) 
must also be set. 




Server Available 


X'08' 


Sent by a the server 


The appropriate state data fields 
(for example, Member Name) must 
also be set. 




CBresynch 


X'OC 


Sent bv a client to the 
server to request a 


This client-bid request with 
^synchronization to follow is 

to send an SRVresynch' 
command to the client. 




Suspend Processing 
for AH Tpipes 


X'14' 


The server sends this 
command to suspend 
ail message activity 
with the client. 
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Tabie 14. Message-Control Information Summary (continued) 



Byte 


Length Content 


Value 


Meaning 


Comments 




Resume Processing 
for AH Tpipes 




The server sends this 
command to resume 
message processing 
with the client. 






Suspend input for 
Tpipe 


X'1C 


The server sends this 
command when it is 
overloaded. 






Resume input for 
Tpipe 


X'20' 


The server sends this 
command when it is 
ready for client input 
(following a Suspend 
Input for tpipe 
command). 






Rosuitw Output for 
Tpipe 




Sent by a client to the 
server to request 
queued tpipe output 
be resent. 






SRVresynch 


X'2C 


Sent by the server to 
a client who has sent 
a CBresynch. 


This command identifies all 
synchronized tpipes within the 
server. 




Resume Output for 
the Special Queue for 
Tpipe 


X'28 ! 


Sent by a client to the 
server to request 
messages from the 
special queue for 
tpipe. 






REGresynch 


X'30' 


Sent by the server to 
a client to specify the 
state of a 

synchronized tpipe. 






REPresynch 


X'34' 


Sent by a client to the 
server to indicate the 
type of 

resynchronization to 
be performed by the 






TBresynch 


X'38' 


Sent by a client to the 

resynchronization for 
a particular tpipe. 




5 


1 Processing fSag 










Message in Special 
Queue 


X'08' 


One or more 
messages in the 
special queue for 
tpipe. Not available 
for Shared Queues. 










sequence numbers 
are maintained for the 
transaction pipe. 






Asynchronous output 


X'20' 


The server is sending 
unsolicited queued 
data messages. 
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Table 14. Message-Control Information Summary (continued) 



Byte 


Length 


Content 


Vaiue 


Meaning 


Comments 






Error Message 
Follows 


X'10' 


An error data 
message follows. 


Set by the server when sending 
a NAK. 


6 


8 


Tpipe Name 




OTMA identic atio 
and processing 
control token. 


Tms name is usea to override 
tne LTERM name on the i/O 
PCB for an IMS application 
program. 


14 


1 


Chain f!ag 






Inis fiag is mandatory for 
multi-segment messages. 






First-in- Chain 




The first segment of a 

multi-segment 

message. 


A rnessacse of only one segment 
is indicated bv setting both the 
first-in-chain ana !ast-in-cnain 
flags. 






Middie-in-Chain 


X'40' 


Part ot a 

multi-segment 

message. 








Last-ln-Chain 


X'20' 


The last segment of a 

multi-segment 

message. 








Discard Chain 


X'10' 


Discard tne current 
chain of message 
segments. 




15 


1 


Prefix fiag 






indicates which sections of the 
message pre'ix ire attached r o 
tnis message. 






State Data 


X'80' 


1 he state-data 
section is included 
witn tne message. 


State data section is mandatory 
for each message. 






Security 


X'40' 


The security section 
is included witn the 
message. 








User Data 


X'20' 


The user-data section 
is induced with the 
message. 


Inis data is specified by an 
OTMA client. 






Application Data 


X'10' 


The application-data 
section is included 
with the message. 




16 


4 


Send-sequence 
number 




The sequence 
number for the 
transaction pipe. 


incremented on every send for 
each transaction pipe. 


20 


2 


Sense Code 




Accompanies a NAK 
message. 




22 


2 


Reason Code 




Accompanies a NAK 
message. 




20 


4 


Aging Vaiue 




Aging value for the 
input user ID. 


The aging value specifies how 
ofte- t-e ca^d utei ID AC I- \ 
shouia be refreshed. The aging 
value flag in byte 5 of tne State 
CaU rJ;* tiso to set This 
value aoes not apply to an ACK 
or NAK messaae. 
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Tabie 14. Message-Control Information Summary (continued) 



Byte 


Length 


Content Value 


Meaning 


Comments 


24 




Recoverataie 
Sequence Number 


The recoverable 
sequence number for 
the transaction pipe- 


incremented on every send of a 
recoverable message using a 
syncnronized transaction pipe. 
Required for ^synchronization 
oniy. 


28 


2 


Segment Sequence 
Number 


Sequence number for 
segments of a 
multi-segment OTMA 
message. 




30 


2 


Reserved 







Explanation of GTIVfA Message-Control Information Fields 

This section provides explanations for the fields in the message-control information 
section of the message prefix. 

Architecture i&vel 

Specifies the OTMA architecture level. The client specifies an 
architecture level, and the server indicates in the response 
message which architecture ievel it is using. The architecture levels 
used by a client and a server must match. 

With IMS Version 8, the oniy valid value is X'OT. 

Mandatory for ail messages. 

Message type Specifies the message type. Every OTMA message must specify a 
value for the message type. The values are not mutually exclusive. 
For example, when the server sends an ACK message to a 
client-submitted transaction, both the transaction and response 
flags are set. 

Data 



Transaction 



Response 
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Specifies server output data sent to the client, if the 
client specifies synchronization level Confirm in the 
state-data section of the message prefix, the server 
also sets Response Requested for the response flag. 
If the client does not specify a synchronization 
level, the server uses the default, Confirm. 

Specifies client input data to the server. 

Whether the server replies with an ACK or NAK 
message depends only on whether Response 
Requested is also set for the response flag. 

Specifies the message type as response message, 
and is set when the message response flag 
specifies Response Requested. 

If this flag is set, the response flag specifies either 
ACK or NAK. 

The send-sequence numbers must match for the 
original data message and the response message. 
Chained transaction input messages to the server 
must always request a response before the next 
transaction {for a particular transaction pipe) is sent. 
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Command Specifies an OTMA protocol command. OTMA 
commands must always specify Response 
Requested for the Response flag. 

Commit Confirmation 

Specifies that commit is complete. This is sent by 
the server when a sync point has completed, and is 
only applicable for send-then-commit transactions. 
I This flag can also be set by an OTMA client to 

I inform the OTMA server to end the IMS 

I conversational transaction. 

Response Flag 

Specifies either that the message is a response message or that a 
response is requested. 

Acknowledgements to transactions include attributes (for that 
transaction) in the application-data section of the message prefix 
only if the transaction specifies Extended Response Requested. 

ACK Specifies a positive acknowledgement. 

MAK Specifies a negative acknowledgement. 

See the sense code field for more information on 
the reason for the NAK. 

Response Requested 

Specifies that a response is requested for this 
message. This can be set for message types of 
Data, Transaction, or Command. 

When sending send-then-commit IMS command 
output, IMS does not request an ACK regardless of 
the synchronization level. 

Extended Response Requested 

Specifies that an extended response is requested 
for this message. Can be set by a client only for 
transactions (or for transactions that specify an IMS 
command instead of a transaction code). 

if this flag is set for a transaction, IMS returns the 
architected attributes for that transaction in the 
appiication-data section of the ACK message. 

If this flag is set for a command, IMS returns the 
architected attributes in the application-data section 
of the ACK message. This flag can be set for the 
IMS commands /DISPLAY TRANSACTION and 
/DISPLAY TRANSACTION ALL. 

Commit-Corrfirmation Flag 

Specifies the success of a commit request. Sent by the server to 
the client in a commit-confirmation message. These messages are 
only applicable for send-then-commit transactions, and are not 
affected by the synchronization-level flag in the state-data section of 
the message prefix. 

Committed Specifies that the server committed successfully. 
Aborted Specifies that the server aborted the commit. 
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Command Type 

Specifies the OTMA protocol command type. 

IMS MTO commands are specified in the application-data section of 
the message. 

CSierst-Bsd Specifies the first message a ciient sends to the 
OTMA server. This command must also set the 
response-requested fiag and the security flag in the 
message-control information section of the 
message prefix. The appropriate state-data fields 
(for example, Member Name) must also be set. 

The security-data prefix must specify a Utoken field 
so the OTMA server can validate the client's 
authority to act as an OTMA client. 

Because the server can respond to the client-bid 
request, this message should not be sent until the 
client is ready to start accepting data messages. 

Server Available 

Specifies the first message the server sends to a 
client. It is sent when the server has connected to 
the XCF group before the client has connected. The 
client replies to the Server Available message with 
a client-bid request. The appropriate state data 
fields (for example, Member Name) must also be set. 

If the client connects first, it is notified by XCF when 
the server connects, and begins processing with a 
client-bid request. 

CBresyrseh Specifies a client-bid message with a request by 
the ciient for resynchronization. This command is 
optional and causes the server to send an 
SRVresynch message to the client. The CBresynch 
command is the first message that a ciient sends to 
the OTMA server when it attempts to resynchronize 
with IMS and existing synchronized tpipes exist for 
the ciient. Other than the CBresynch message 
indicator in the message prefix, the information 
required for the message prefix should be identical 
to the client-bid command. 

If IMS receives a client-bid request from the ciient 
and IMS is aware of existing synchronized tpipes, 
IMS issues informational message DFS2394I to the 
MTO. IMS resets the recoverable send- or 
receive-sequence numbers to 0 (zero) for ail the 
synchronized tpipes. 

Related Reading: For more information on 
resynchronization, see "Client/Server 
Resynchronization with OTMA" on page 28. 

Suspend Processing lor AH Tpipes 

Specifies that the server is suspending all message 
activity with the client. All subsequent data input 
receives a NAK message from the server. Similarly, 
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the client should send a NAK message for any 
subsequent server messages. 

If a client wishes to suspend processing for a 
particular transaction pipe, it must submit a /STOP 
TPIPE command as an OTMA message. 

Resume Processing tor All Tpipes 

Specifies that the server is resuming message 
activity with the client. 

if a client wishes to resume processing for a 
particular transaction pipe that has been stopped, it 
must submit a /START TPIPE command as an 
OTMA message. 

Suspend irsput for Tpipe 

Specifies that the server is overloaded and is 
temporarily suspending input for the transaction 
pipe. Ail subsequent client input receives NAK 
messages for the transaction pipe specified in the 
message control information section of the 
message prefix. A response is not requested for this 
command. 

This command is also sent by IMS when the master 
terminal operator enters a /STOP TPIPE command. 

Resume Input for Tpipe 

Specifies that the server is ready to resume client 
input following an earlier Suspend Input for tpipe 
command. A response is not requested for this 
command. 

This command is also sent by IMS when the IMS 
master terminal operator issues a /START TPIPE 
command. 

Resume Output lor Tpipe 

Specifies one or multiple tpipe names to the OTMA 
server. All queued output on the tpipes will be 
resent again. 

Resume Output lor the Special Queue for Tpipe 

Specifies that a client is requesting to retrieve 
messages from the special queue for tpipe. There 
are command options to retrieve messages. See 
"Format of OTMA State Data for Resume Output for 
the Special Queue for Tpipe" on page 87 for more 
information about the available command options. 

Specifies the server's response to a client's 
CBresynch command. This command specifies the 
states of synchronized transaction pipes within the 
server (the send- and receive-sequence numbers). 

This command is sent as a single message (with 
single or multiple segments), and an ACK is 
requested. 

Specifies the send-sequence number and the 



SRVresynch 



REQresyrsch 
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receive sequence for a particular tpipe. 
REQresynch is sent from IMS to a client. 

REPresyrsch Specifies the client's desired state information for a 
tpipe. A client sends the REPresynch command to 
IMS in response to the REQresynch command 
received from IMS. 

TBresynch Specifies that the client is ready to receive the 
REQresynch command from IMS. 

Processing Flag 

Specifies options by which a client or server can control message 
processing. 

Synchronized Tpipe 

Specifies that the transaction pipe is to be 
synchronized. Allows the client to resynchronize a 
transaction pipe if there is a failure. Only valid for 
commit-then-send transactions. 

This flag causes input and output sequence 
numbers to be maintained for the transaction pipe. 
All transactions routed through the transaction pipe 
must specify this flag consistently (either on or off). 

Asynchronous Output 

Specifies that the server is sending unsolicited 
queued output to the client. This can occur when 
IMS inserts a message to an alternate PCB. 

Certain IMS commands, when submitted as 
commit-then-send, can cause IMS to send the 
output to a client with this flag set. in this case, the 
OTMA prefixes contain no identifying information 
that the client can use to correlate the output to the 
originating command message. These command 
output data messages simply identify the 
transaction-pipe name. IMS can also send some 
unsolicited error messages with only the 
transaction-pipe name. 

Error Message Follows 

Specifies that an error message follows this 
message. This flag is set for NAK messages from 
the server. An additional error message is then sent 
to the client. 

The asynchronous-output flag is not set in the error 
data message, because the output is not generated 
by an IMS application. 

Message in the Special Queue 

Specifies that one or more messages exist in the 
special queue for the tpipe to be delivered. This flag 
is always on for an IMS output message that has 
been sent from the special queue for tpipe. 
Therefore, this flag can be used to determine 
whether there is any message in the special queue 
for an IMS output message that has been sent from 
the regular queue for tpipe. 
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To determine whether the IMS output message is 
sent from the regular queue or from the special 
queue, check the "From Special Queue" flag in the 
Server State of the State Data. 

For Shared Queues, this flag is not available. To 
determine if there are any messages on the special 
queue, issue the "Resume Output for the Special 
Queue for tpipe" protocol command. 

Tpipe Name Specifies the transaction-pipe name. For IMS, this name is used to 
override the LTERM name on the I/O PCB. This field is applicable 
for all transaction, data, and commit-confirmation message types, it 
is also applicable for certain response and command message 
types. 

Related Reading: See also the Destination Override field in 
"Explanation of OTMA State Data Fields" on page 88. 

Chain Hag Specifies how many segments are in the message. This flag is 
applicable to transaction and data message types, and it is 
mandatory for multi-segment messages. 

First-Ssi-Chairj Specifies the first segment in a chain of segments 
which comprise a multi-segment message. 
Subsequent segments of the message only need 
the message-control information section of the 
message prefix. Other applicable prefix segments 
(for example, those specified by the client on the 
transaction message) are sent only with the first 
segment (with the first-in-chain flag set). 

if the OTMA message has only one segment, the 
last-in-chain flag should also be set. 

Mjiddie-irs-Chairs 

Specifies a segment that is neither first nor last in a 
chain of segments that comprise a multi-segment 
message. These segments only need the 
message control information section of the 
message prefix. 

Restriction: Because the client and server tokens 
are in the state-data section of the message prefix, 
they cannot be used to correlate and combine 
segmented messages. The transaction-pipe name 
and send-sequence numbers can be used for this 
purpose; they are in the message-control 
information section of the message prefix for each 
segment. 

Last-in-Chairs Specifies the last segment of a multi-segment 
message. 

Discard Chairs 

Specifies that the entire chain of a multi-segment 
message is to be discarded. The last-in-chain flag 
must also be set. 

Prefix Fiag Specifies the sections of the message prefix that are attached to 
the OTMA message. Every message must have the 
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message-control information and state-data sections, but any 
combination of other sections can be sent with an OTMA message. 

State data Specifies that the message includes the state-data 
section of the message prefix. See "OTMA State 
Data" on page 82. 

Security data Specifies that the message includes the 

security-data section of the message prefix. See 
"OTMA Security Data" on page 91. 

User data Specifies that the message includes the user-data 
section of the message prefix. See "OTMA User 
Data" on page 93. 

Application data 

Specifies that the message includes the 
application-data section of the message prefix. See 
"OTMA Application Data" on page 94. 

Sersd-Sequence Number 

Specifies the sequence number for a transaction pipe. This 
sequence number is updated by the client and server when sending 
s or transactions. 



Recomrrjersdatiori: Increment the number separately for each 
transaction pipe. 

This number can also be used to match an ACK or NAK message 
with the specific message being acknowledged. 

Serjse Code Specifies the sense code that accompanies a NAK message. See 
Chapter 4, "OTMA Diagnostic Information," on page 65. 

Reason Code Specifies the reason code that accompanies a NAK message. This 
code can further qualify a sense code. 

Userid Aging Value 

Specifies the aging value in seconds for the input user ID. This field 
is different from the aging value specified in the OTMA client-bid 
command for OTMA connection. The aging value in the client-bid 
command sets the default aging value for ail the OTMA user IDs; 
however, the Userid Aging Value overrides the default aging value 
for a specific user ID. if the userid aging value is less than 300 
seconds {5 minutes), IMS always creates a non-cached ACEE, 

Recoverable Sequence Number 

Specifies the recoverable sequence number for a transaction pipe. 
Incremented on every send of a recoverable message using a 
synchronized transaction pipe. Both the client and the server 
increment their recoverable send-sequence numbers and maintain 
them separately from the send-sequence number. Required for 
resynchronization only. 



i Reading: For more information on resynchronization, see 

"Client/Server Resynchronization with OTMA" on page 28. 

Segment Sequence Number 

Specifies the sequence number for a segment of a multi-segment 
message. This number must be updated for each segment, 
because messaqes are not necessarily delivered sequentially by 

XCF. 
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This number must have a value of 1 if the message has only one 
segment. 



OTWIA State Data 

The state data is mandatory for any message. It immediately follows the 
message- control information section in the message prefix. It contains 
transaction-related information. 

The state-data section has different formats for transaction-related information and 
for commands. State data for commands can be followed by a security-data 
section. 

The following topics provide additional information: 

• "Format of OTMA State Data for Transaction- Related Information" 

• "Format of OTMA State Data for Server-Available and Client-Bid Commands" on 
page 84 

• "Format of OTMA State Data for SRVresynch Command" on page 84 

• "Format of OTMA State Data for REQresynch Command" on page 85 

• "Format of OTMA State Data for REPresynch Command" on page 85 

• "Format of OTMA State Data for TBresynch Command" on page 86 

• "Format of OTMA State Data for Resume Output for Tpipe" on page 87 

• "Format of OTMA State Data for Resume Output for the Special Queue for 
Tpipe" on page 87 

• "Explanation of OTMA State Data Fields" on page 88 

Format of OTIVf A State Data for Transaction-Related Information 

Table 15 shows the format of state data {column 2 from Table 13 on page 71) for 
transaction-related information. The summary includes byte, length, content, 
hexadecimal value, the meaning, and includes usage comments. The state data 
fields are defined in "Explanation of OTMA State Data Fields" on page 88. 



Table 15, State Data Format for Transaction-Related Information 



Byte 


Length Content 


Value 


Meaning 


Comments 


0 


2 Length 




Le jt" of fx 
state-data seer. ion. 


includes the length field itself. 


2 


1 Server State 










Conversational State 


X'80' 


t-or a conversational 
transaction. 


Set by the server and client 
when sending conversational 
data. 




Response Mode 


X'40' 


For a response-mode 
transaction. 


Set by the server when sending 
output. 




From Special Queue 


X'20' 


Output from the 
soeciai queue ror 
tDipe. 


Set by the server when sending 
output. 




Rerouted Message 


X'08' 


ror uMO output. 


Set by the server when 
processing a reroute request 
from IMS Connect. 


3 


1 Synchronization fiag 










Commit-then-send 


X'40' 


A commit-then-send 
transaction. 


The server commits output 
before sending It. 
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Tabie 15. State Data Format for Transaciion-Reiated Information (continued) 



Byte 


Length 


Content 


Value 


Meaning 


Comments 






Send-then-commit 


X'20' 


A send-then-commit 
transaction. 


The se vc sc ^ds julout bofore 
committing it. 


4 


1 


Synchronization 
Level 






The default is Cc m 






None 


X'00' 


No synchronization. 


^orvcr aprJiMtKV docs net 
request an ACK message when 
sending output to a ciient. 






Confirm 


x'or 


Synchronize. 


server sends transaction output 
with the Rewnse Rex -■skd 
flag set. 






Syncpt 


X'02' 


This message is part 
of a protected 
conversation. 


The resources updated under 
this conversation use the 
two-phase commit protocol. 


5 


1 


Client Flags 












Send Only Message 


X'80' 


This is a send only 
message; the 
response is placed 
on the speciai queue. 


This flag is valia only if the ciient 
sequested a specia: Queue 
durina open. 






Set Aging Value 


X'40' 


To accept the aging 


ThR flag rsirucls WS to accept 
the aging value specified at byte 

information. 






Reroute Request 


X'20' 


Reroute Requested. 


Scenes ni s flaa orouies CMC 
output to the destination tnat is 
5L"2l "e Destination 
Override field. 


6 


8 


Map Name 




Data rormar map 
used by tne server to 
mao application input 
or output. 


Optional. 


14 


16 


Server Token 




Server name. 


ivlust oe returned bv the client to 
the server on responses. 


30 


16 


Correlator Token 




A ciient token ro 
correlate input with 
output. 


Optional. 


46 


16 


Context !D 




RRS Context ID 


Used with SYNCLVL=02 and 
protected conversations. 


62 


8 


Destination Override 




Override the 
destination name for 
server output. 


Optional. 


70 


2 


Server user data 
length 




Length of the server 
data 


The length does not include the 
length field itself. 


72 




Server user data 




Any data needed by 
the server. 


variable length. Optional. 
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Format of OTMA State Data for Server-Available and Client-Bid 
Commands 

Table 16 summarizes the format for state data for command messages. The 
summary includes byte, length, content, hexadecimal value, the meaning, and 
includes usage comments. 



Table 16. Server-Available and Client-Bid Command Format 



Byte Length Content 




Meaning 


Comments 


0 2 Length 




Length of the 
state-data section. 


Includes the length field itself. 


2 16 Member Name 




XGF member name 
of originating server. 




18 8 Originator's Token 




XGF member token 
of the originator of 
the message. 




26 8 Destination Token 




XCF member token 
of the destination of 
the message. 




Note: The following fields are present only for 


client- bid c 


jmmands. 




34 8 DRU Exit Name 




Destination 
Resolution exit 
routine name. 




42 2 MaxBtecksize 




Maximum block size 
for XCF 

transmissions from 
server to client. 


Optional. 


44 1 Client-Bid Flag 


Purge Not Deliverable 


X'20' 


Specifies that OTMA 
delete the CMO 
IOPCB output 
response if IMS 
Connect is down or 
leaves the XCF 
group. 




Special Queue 


X'80' 


Specifies that a 
special queue for a 
tpipe Is needed. 




4b 1 Reserved 


46 4 Aging value 




AGEE aging value in 
seconds. 


The minimum value for caching 
support is 300 seconds (5 
minutes). 


50 4 Hash Table Size 




Hash table size is 
used for processing 
multi-segment 
messages. 


Suggested value is X'00000065', 



Format of OTMA State Data for SRVresynch Command 

The SRVresynch command is sent by IMS to pass all its known synchronized tpipe 
names to the client. If the command data can not fit into a single buffer, chained 
multi-segment buffers will be sent instead. Table 17 on page 85 summarizes the 
format of state data for the SRVresynch command. The summary includes byte, 
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length, content, hexadecimal value, the meaning, and includes usage comments. 
The state data fields are defined in "Explanation of OTMA State Data Fields" on 
page 88. 



I able 17. SRVresynch Command Format 



Byte Length 


Content 


Value 


Meaning 


Comments 


0 2 


Length 




Length of the 
state-data section. 


Includes the length field itself. 


2 8 


Tpipe Name 




The transaction pipe 
name. 


The tpipe name can be repeated 
as necessary. 


Format of OTMA State Data for REGresyrtch Command 




The REQresynch command is used by IMS to pass the send-sequence number and 
the receive sequence for a specific tpipe to the client. Table 18 summarizes the 
format of state data for the REQresynch command. The summary includes byte, 
length, content, hexadecimal value, the meaning, and includes usage comments. 
The state data fields are defined in "Explanation of OTMA State Data Fields" on 
oaae 88. 


Table 18, REQresynch Command Format 








Byte Length 


Content 


Value 


Meaning 


Comments 


0 2 


Length 




Length of the 
state-data section. 


Includes the length field itself. 


2 8 


Tpipe Name 




The transaction pipe 
name. 




10 4 


Send-sequence 
number 




IMS recoverable 
send-sequence 
number for the 
transaction pipe. 




14 4 


Receive-sequence 
number 




IMS recoverable 
receive-sequence 
number for the 
transaction pipe. 




18 1 


Tpipe Fiaci 1 




Reserved for future 
use. 




19 1 


Tpipo V <q ? 




Reserved for future 
use. 




20 6 


RESERVED 









Format of OTMA State Data for REPresynch Command 

The REPresynch command is sent by the client in reply to the REQresynch request 
from IMS. it contains the desired state information for a tpipe. Table 19 summarizes 
the format of state data for the REPresynch command. The summary includes byte, 
length, content, hexadecimal value, the meaning, and includes usage comments. 
The state data fields are defined in "Explanation of OTMA State Data Fields" on 
page 88. 



Table 19, REPresynch Command Format 



Byte 


Length 


Content 


Value 


Meaning 


Comments 






2 


Length 




Length of the 
state-data section. 


Includes the len 


gth field itself. 
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Table 19. REPresynch Command Format (continued) 



Byte 


Length 


Content 


Yaiue 


yeaning 


Comments 


2 


8 


Tpipe Name 




The transaction pipe 
name. 




10 


4 


Send-sequence 
number 




Client recoverable 
send-sequence 
number for the 
transaction pipe. 




14 


4 


Receive-sequence 
number 




Client recoverable 
receive-sequence 
number for the 
transaction pipe. 








Tpipe Fl89 ^ 






Mutually excsuswe values. 






Continue 


X'00' 


The last message 
has been received 
and IMS continues 
processing for this 
synchronized 
transaction pipe. 








Dequeue Last Output 


X'04' 


IMS can dequeue the 
last output message. 
The recoverable 
send-sequence 
number is updated. 








Reset Sequence 
Numbers 


X'08' 


IMS resets the 
recoverable 
send-sequence 
number and the 
recoverable 
receive-sequence 
number, as passed in 
this command. 








Stop Tpipe 


X'OC 


IMS stops this 
synchronized 
transaction pipe. 








Stop Tpipe & wait for 
TBresynch 


X'10' 


IMS stops this 
synchronized 
transaction pipe and 
waits for TBresynch 
from the client. 




19 


1 


Tpipe Flag 2 




Reserved. 




20 


6 


Reserved 









Format of OTMA State Data for TBresynch Command 

The TBresynch command is sent by the client to IMS if the client decides it is ready 
to receive REQresynch from IMS. The TBresynch command can be issued in the 
following two situations: 

• The client has received an ACK message after sending REPresynch with "stop 
and wait for TBresynch" to IMS. 

• The client may request a TBresynch with IMS at any time after the initial 
nondeferred resynchronization has completed for this tpipe. 
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Table 20 summarizes the format of state data for the TBresynch command. The 
summary includes byte, length, content, hexadecimal value, the meaning, and 
includes usage comments. The state data fields are defined in "Explanation of 
OTMA State Data Fields" on page 88. 



Table 20. TBresynch Command Format 



Byte 


Length Content 


Value 


Meaning Comments 




0 


2 Length 




Length of the Includes the leng 
state-data section. 


th field itself. 


2 


8 Tpipe Name 




The transaction pipe 
name. 





Format of OTMA State Data for Resume Output for Tpipe 

This command is sent by the client to force any queued output to be resent again. 
The number of tpipes and tpipe names are needed in the command. 

If the special queue for the tpipe exists and holds messages, those messages will 
also be sent to the client. Table 21 summarizes the format of state data for Resume 
Output for tpipe. The summary includes byte, length, content, hexadecimal value, 
the meaning, and includes usage comments. 



Table 2i. Resume Output for f pipes Command Format 



Byte 


Leng*h 


Content 


Value 


Meaning 


Comments 


0 




Lerscsih 




Length of the 
state-data section. 




2 


2 


Tpipe Count 




Number of tpipe 
names in the 
command. 




4 


8 


Tpipe Name 




The transaction tpipe 
name. 


Different tpipe names can be 
added as necessary. 



Format of OTMA State Data for Resume Output for the Special Queue 
for Tpipe 

I An OTMA client sends the command to inform IMS to deliver one or all queued 

I messages on the special queue for tpipe. if this command is not issued, messages 

I will be held in the special queue. However, the option specified in the command can 

i be used to request how IMS holds and delivers messages. One of the four options 

i in Table 22 can be specified in the State Data, if the client or XCF returns a NAK 

! message to IMS, the current option is reset to No-Auto, which is the default. 

Table 22 summarizes the format of state data for Resume Output for the special 
queue tpipe. The summary includes, as appropriate, byte, length, content, 
hexadecimal value, and the meaning. The state data fields are defined in 
"Explanation of OTMA State Data Fields" on page 88. 



Table 22. Resume Output for the Special Queue for Tpipes Command Format 



Byte 


Length 


Content 


Value 


Meaning 


0 




Length 




Lengtn of tne stare-aata 
section. 






Option 
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Table 22. Resume Output for the Special Queue for Tpipes Command Format (continued) 



Byte 


Length 


Content 


Vaiue 


IVieamng 






No -Auto 




Exhaust all the messages in 
the queue oniv when the 
command is issued. F his is tne 
default. 






One Only 




Deliver one message in the 
queue when the command is 
issued. 






Auto 


X ! 02' 


Exhaust all the messages in 
the queue. After tnat. 
automatically deliver messages 
wnen they are Queued. 






Auto-One 


X'04' 


Deliver one message 
automatically when a message 
is available nl •■queue ~"c 
message could already be in 
the queue or it might be 
delivered later. After ihe 
message is delivered, this 
option is reset to No-Auto. 



Explanation of QTIWIA State Data Fields 

This section provides explanations for the content of the state data fieids of the 
message prefix: 

Length Specifies the total length of the state-data section of the message 

prefix, including the length field. 

Server State Specifies the mode in which the transaction is running. 

Conversational State 

Specifies a conversational mode transaction. The server sets 
this state when processing a conversational-mode transaction. 
This state is also set by the client when sending subsequent 
IMS conversational data messages to IMS. 

Response Mode 

Specifies a response-mode transaction. Set by the server when 
processing a response-mode transaction. 

This state has little significance for an OTMA server, because 
OTMA does not use sessions or terminals. 

From Special Queue 

Specifies that the output message was sent from the IMS 
special queue for the tpipe. The server initially sets this flag 
when sending a commit-then-send output message. The client 
also needs to set this flag when sending the subsequent ACK 
or NAK to IMS. 

Synchronization Hag 

Specifies ihe commit mode of the transaction. This flag controls and 
synchronizes the flow of data between the client and server. 
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Comrrsit-thers-Sersd 

Specifies a commit-then-send transaction. The server commits 
output before sending it; for example, IMS inserts the output to 
the IMS message queue. 

Serjd-then-Commit 

Specifies a send-then-commif transaction. The server sends 
output to the client before committing it. 

Syrsehromzatiosi Levsf 

Specifies the transaction synchronization level, the way in which the 
client and server transaction program (for example, IMS application 
program) interacts with program output messages. 

The default is Confirm. IMS always requests a response when 
sending commit-then-send output to a client, 

Norse 

Specifies that no synchronization is requested. The server 
application program does not request an ACK message when it 
sends output to a client. 

None is only valid for send-then-commit transactions. 
Confirm 

Specifies that synchronization is requested. The server sends 
transaction output with the response flag set to Response 
Requested in the message-control information section of the 
message prefix. 

Confirm can be used for either commit-then-send or 
send-then-commit transactions. 

Syrsept 

Specifies that the programs participate in coordinated commit 
processing on resources updated during the conversation under 
the RRS/MVS recovery platform. A conversation with this level 
is also called a protected conversation. 

Client Flags Specifies optional processing requested by the client. 

Sersd-Orsiy Message 

This is a send only message; the response is placed on the 
special queue. This flag is valid only if the client requested a 
special queue during open. 

Reroute Request 

Setting this flag reroutes CMO output to the destination that is 
specified in the Destination Override field. 

Set Aging Value 

Specifies that the aging value in the message-control 
information message prefix is to be used for this userid. This 
aging value will override the member aging value specified in 
the client-bid time for this message. If this option is not set, 
member aging value will be used to refresh the cached ACEE 
for the userid. 

Map Name Specifies the formatting map used by the server to map output data 
streams (for example, 3270 data streams). Although OTMA does 
not provide MFS support, you can use the map name to define the 
output data stream. The name is an 8-byte MOD name that is 
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placed in the I/O PCB. IMS replaces this field in the prefix with the 
map name in the I/O PCB when the message is inserted. 

The map name is optional. 

Server Token Specifies the server name. The Server Token must be returned by 
the client to the server on response messages (ACKs or NAKs). 
For conversational transactions, the Server Token must also be 
returned by the client on subsequent conversational input. 

Correlator Jokers 

Specifies a client token to correlate input with output. This token is 
optional and is not used by the server. 

Recommendation: Clients should use this token to help manage 
their transactions. 

Corstext ID Specifies the RRS/MVS token that is used with SYNCLVL=02 and 
protected conversations. 

Destination Override 

Specifies an LTERM name used to override the LTERM name in 
the IMS application program's I/O PCB. This override is used if the 
client does not want to override the LTERM name in the I/O PCB 
with the transaction-pipe name. 

This optional override is not used if it begins with a blank. 

Server User Data Length 

Specifies the length of the server user data, if any. The maximum 
length of the server user data is 256 bytes. The server user data 
length is not included in the length calculation. 

Server User Data 

Specifies any data needed by the server. If included in a transaction 
message by the client, it is returned by the server in the output data 
messages. 

Member Name 

Specifies the XCF-member name of the originating server. 

Originators Jokers 

Specifies the XCF-member token of the originator (either client or 
server) of the message. 

Destination Token 

Specifies the XCF-member token of the destination (either client or 
server) of the message, 

DRU Exit Name 

Specifies the name of the OTMA Destination Resolution exit 
routine. 

fVSaxBfocksize Specifies the maximum block size for XCF conversations between 
the server and the client. 

Client-Bid Flag 

Specifies the options for the client-bid flag. There is currently one 
option available. 

Special Queue 

Specifies that a special queue for a fpipe is needed. The 
special queue can hold commit-then-send output that is NAK'd, 
as well as alternate PCB output for an OTMA client. The output 
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messages in the queue will not be delivered until the client 
requests that those messages be delivered. Use of the special 
queue is optional. Without the special queue, a regular queue 
for the tpipe will be used to hold and deliver all the 
Commit-then-send output messages. The default is no special 
queue for a tpipe. 

OTMA resynchronization protocol currently does not support the 
special queue. 

Agmg Value Specifies the access control environment element (ACEE) aging 
value, in seconds. IMS creates an ACEE if the age of the current 
ACEE is greater than this value. 

i The minimum value for caching support is 300 seconds (5 minutes), 

i If the aging value specified is less than the minimum, IMS always 

I creates a non -cached ACEE. 

Hash Table Size 

Defines the size of the IMS OTMA hash table for processing 
multi-segment messages input. The table is used to correctly chain 
ail the input segments together. IMS will create the table based on 
the size specified. Suggested value is X'00Q00085'. 



GTIVf A Security Data 

The security-data section is mandatory for every transaction or command, and is 
optional for OTMA protocol commands. 

Format of OTMA Security Data 

Table 23 is a summary of the content of the security-data section of the message 
prefix. The summary includes, as appropriate, byte, length, content, hexadecimal 
value, the meaning, and includes usage comments. More information about the 
content follows the table in "Explanation of OTMA Security Data Fields" on page 92. 



Table 23. Content of Security Data Fields 



Byte 


Length Content 


Value 


Meaning 


Comments 




2 Length 




Length of the 
security-data section. 


Includes the length field itself. 


2 


1 Security flag 










No Security 


N 


No RACF checking is 
done. 


It is assumed that the user ID 
and password are already 
verified. 




Check 


C 


RACF checks 
transactions and 
commands. 


Transaction and command 
authorization RACCHECKs are 
performed (TCLASS and 
CCLASS). 




Fuli 




RACF checks 
transactions, 
commands, and 
regions. 


Transaction, IMS command, and 
MPP region authorization 
RACCHECKs are performed. 


3 


1 Reserved 










1 Utoken Length 




Length of Utoken 
plus the length of 
Utoken Type. 


Length does not include length 
field itself. 
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Table 23. Content of Security Data Fields (continued) 



Byte 


Length Content 


^/aiue 


yeaning 


Comments 




1 Ulokon Typo 


X'OO' 


Type of data to 
follow. 






Utoken 




The user token. 


Variable length, from 1 to 80 
bytes. 




1 User ID Length 




Length of the user ID 
plus the length of the 
User ID Type, 


Length does not include length 
field itself. 




1 User ID Type 


X'02' 


Type of data to 
follow. 






User ID 




The user ID. 


Variable length, from 1 to 8 
bytes. 




u Profiie Length 




Length of the profile 
plus the length of the 
Profile Type. 


Length does not include length 
field itself. 




1 Proflie Type 


X'03' 


Type of data to 
follow. 






Profiie 




The SAF profile. 


Variable length, from 1 to 8 
bytes. 



Explanation of OTMA Security Data Fields 

The following information provides additional detail on the content of the 
security-data section of the message prefix: 

Lemgth Specifies the length of the security-data section of the message 

prefix, including the length field. 

Security Fiag Specifies the type of security checking to be performed. It is 
assumed that the user ID and password are already verified. 

Mo Security Specifies that no security checking is to be done. 

Check Specifies that transaction and command security 

checking is to be performed. 

Fuli Specifies that transaction, command, and MPP 

region security checking is to be performed. 

Reserved After the reserved field, the following three fields can be omitted or 
appear in any order. Each field has the following structure: 

• Length field 

• Field type 

• Data field 

The length field is not calculated in the length calculation. The 
actual length of the user ID or profile should not be less than the 
value specified for the length of each field. 

Utoken Length 

Specifies the length of the user token plus the length of the user 
token type. 

□takers Type Specifies that this field contains a user token. 
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Utokesi Specifies the user token. The user ID and profile are used to create 

the user token. The user token is passed along to the IMS 
dependent region. 

If the client has already called RACF, it should pass the Utoken with 
field type X'OO' so that RACF is not called again. 

User ID Lerjgth 

Specifies the length of the User ID plus the User ID type. 
User ID Type Specifies that this field contains a user ID. 
User ID Specifies the actual user ID. 

Profile Length 

Specifies the length of the profile plus the length of the profile type. 
Profile Type Specifies that this field contains a profile. 

Profile Specifies the system authorization facility (SAF) profile. For RACF, 

this is the group name. 



QTIVf A User Data 



The user-data section is variable length and follows the security-data section of the 
message prefix. It can contain any data. 



Format of OTMA User Data 

Tab < 24 s. a -sum"n_:ry <•! the ort 'it uf lie J-ser daLi so nor of ihe "n< ssi.it. 
prefix "he si-mnarv incudes as an^opnate Dvfe lergih confer i hexadecimal 
value tr meaning and in udo& jsag< corrms-'nts. Vlor-j irf- ■•manon about tr 
consent "oliows *ne *able n Fxd anchor of r ^ MA Use! IVfa -eas 



Table 24. Content of User Data Fields 



Byte 


Length 


Content 


VaSue 


Moanmg 


Comments 


0 




Length 




Length of the 


The lengtn includes the lengt 
field itself. 


2 




User data 




The user data. 


Optional: vanaole length. 



Explanation of OJMA User Data Fields 

The following information provides additional detail on the content of the user-data 
section of the message prefix: 

Length Specifies the length of the user-data section of the message prefix, 

including the length field. The maximum length of the user data is 
1024 bytes. 

User Data Specifies the optional user data. This data is managed by the client, 
and can be created and updated using the DFSYDRUO exit routine. 
The server returns this section unchanged to the client as the first 
segment of any output messages. 
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OTMA Application Data 

The application-data section is variable length and follows the user-data section of 
the message prefix. You include IMS commands and transactions in the 
application-data section. The data in this section is unchanged by the receiver 
(server or client), and is transmitted directly to the server application program or to 
the client application program. 

Format of OTMA Application Data 

Table 25 is a summary of the content of the application-data section of the message 
prefix. The summary includes, as appropriate, byte, length, content, hexadecimal 
value, the meaning, and includes usage comments. More information about the 
content follows the table in "Explanation of OTMA Application Data Fields." 



Table 2b. Application Data 



Byte 


Length 


Content 


Value 


Meaning 


Comments 


0 


2 


Length 




Length of the 

application-data 

section. 


The length includes the length 
field itself. The maximum length 
Is 32KB (32767 bytes). 


2 


2 


ZZ 




Application data IMS 
ZZ fields. 








Application data 




The application data. 


Variable length. The maximum 
length of application data is 
32KB-4. 



Explanation of GTIrVIA Application Data Fieids 

The following information provides additional detail on the content of the 
application-data section of the message prefix: 

Length Specifies the length of the application-data section of the message 

prefix, including the length field. 

Application data 

Specifies the optional application data. 

Multiple send requests might be required for a server output 
segment. For a client's transaction, the transaction code is specified 
in the first 8 bytes of the data area following the LLZZ. For 
transactions specified with MULTSEG, the standard IMS LLZZ format 
is required for each segment. The transaction code is only required 
in the first segment. 



Sample OTMA Messages 

This section shows three sample OTMA messages. They are not necessarily 
related to each other, but are intended to show what OTMA messages look like 
when fully constructed, including the parts of the message prefix. 

Figure 34 on page 95 shows an OTMA client-bid message. The total length of the 
state-data section plus the security-data section of the message prefix is X'8C 
bytes. 
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MESSAGE CONTROL INFORMATION: 



STATE DATA + SECURITY DATA: 

6G36C3D3 C9C5D5E3 F1404040 40404046 

40400100 00G10G03 00020100 00010003 

0001C4C6 E2E8C4D9 E4F02000 00007FFF 

FFFF0000 00650056 C3525100 50018059 

15569555 55555555 55555555 B7B686B0 

81A61515 1B1B1B1B 1B1B1B1B B7B686B0 

81A61515 55555555 55555555 8C918CA4 

15151515 55555555 55555555 09151515 
15151515 15151515 15151515 

Figure 34. OTMA Client-Bid Message 




Figure 35 shows an OTMA transaction message. The total length of the state-data, 
security-data, and application-data sections of the message prefix is X'D6' bytes. 



MESSAGE CONTROL INFORMATION : 



TPIPE1 ff}j 



STATE DATA + SECURITY DATA + APPLICATION DATA: 



00480029 

00000000 

E2F0FGF0 
40404040 
40404040 
80465551 
55555555 
55555555 
A781B0B7 
8CB6A5A5 
0O00CID7 
D3D3D640 
40404040 
40404040 



0100E3C5 

00000000 

F0F1OG00 
40404040 
40400000 



E2E3D4C1 D74O00O0 
00000000 0000C9D4 
00000000 00004040 
40404O40 40404O40 
0056C652 51005001 




55555555 
55555555 
A4155555 
A415B7BD 
D6D3FIF8 
40404040 
40404040 
4040 



55555555 55555555 
55555555 555586A3 
55555555 5555B1B7 
B7A41515 15150038 
4040E2C1 E840C8C5 
40404040 40404040 
40404040 40404040 



..AP0L18 SAY HE 



Figure 35. OTMA Transaction Message 

Figure 36 on page 96 shows an OTMA response message. The total length of the 
state-data, security-data, and application-data sections of the message prefix is 
X ! EE ! bytes. 
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MESSAGE CONTROL INFORMATION: 

01A08000 O0OOE3D7 C9D7C5F1 40408600 j „ff. . , .TPIPE1 

OOOOOOOi OuOOuOOU OuOOuOOl 0U010000 j 

STATE DATA + SECURITY DATA + APPLICATION DATA: 

001800J0 0100E3C5 E2E3D1C1 D710AB7F 

28EB9FAD 9A024040 40404040 4040C904 

E2F0F0F0 FOFiOOOO 00000000 00004010 

40404040 40404040 40404010 10404010 

40404O4O 40400000 0Q56C652 51005001 

80165531 95535535 35535555 5s55i55i 

55555555 55555555 55555555 55555555 

55555555 55555555 55555555 555586A3 

A781B0B7 A4] 13513 i3J.i3J.b3 b 3 5b8]B7 

8CB6A5A5 A415B7BD B7A41515 15150050 

03O0D6E4 E3E2C5C7 40D5D67E F0F0FOFO 

F140E2D7 C5C3C9C6 C9C5C440 E2C5C7E2 

C9E9C57E F0FOFOF8 F06B4OE2 C5C7D5D6 

7EF0F0F0 FOF3404O 40404040 40F67EC3 

D60340F6 F04040F7 7EC3D6D3 40F7 

Figure 36, OTMA Response Message 



,. ..IESIMAP f" 
.. Y.. IM 

SO0OO1........ 
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Chapter 6, 0TIV1A Architected Transaction Attributes 

This chapter describes the syntax of architected command output. 

When you issue an IMS /DISPLAY TRANSACTION command from OTMA, the output is 
in the form of an OTMA message, returned to the client in the application-data 
section of the message prefix. Table 26 shows the Attributes Segment for a given 
transaction. The description includes byte, length, content, hexadecimal value, the 
meaning, and includes usage comments where appropriate. 



Table 26. Transaction Attributes Segment 



Byte Length 


Content 


Value 


Meaning 


Comments 


0 2 


Length 




Length of the 
Transaction Attributes 
Segment (LL). 


This length includes the length 
field itself. 


2 


ZZ 








4 8 


Transaction Code 




The 8-byte IMS 
transaction code. 




12 1 


Transaction type 
flag 1 






The flag 1 values are mutually 
exclusive. 






X'00 ! 


A valid OTMA 
transaction. 






CPIC 


X'04 ! 


A oPi-C (APPC) 
transaction. 






FPX 


X'08' 


A Fast Patn-exclusive 
transaction. 






FPP 


X'OC 


A hast Patn-ootential 
transaction. 






MSC 


X'10 ! 


An MSC remote 
transaction. 






Invaisd Syntax 


X'FE' 


Syntax error. 


The data area contains the text 
of the error. 




Invalid 


X'FP 


1 ransaction not 
found, or invalid. 




13 1 


Transaction type 
flag 2 






The flag 2 values are not 
mutually exclusive. 




Response 


X'80' 


A' IVIS -'spons-' 
moae transaction. 






Conversation 


X'40' 


An IMS 

conversational 

transaction. 






Update 


X'20 ! 


The rransaction nas 
update capability. 






Irrecoverable 


X'10 ! 


The rransaction is 
defined as 
irrecoverable. 






Multi-Segment 


X'08'a 


The n inaction "as 
multiple segments. 






Uppercase 


X'Q4 ! 


Uppercase translation 
requested. 
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Table 26. Transaction Attributes Segment (continued) 





Length 


Content 




Meaning 


Comments 


14 


1 


Transaction Status 






The indicated values are not 
mutually exclusive. 






S70P 


X'80' 


The transaction input 
queueing is stopped. 


One of the following IMS 
commands was issued for the 
transaction: 

• /STOP 

• /PURGE 
















OLC 


X'40' 


The transaction input 
queueing is stopped. 


One of the following IMS 
commands was issued for the 
transaction: 

• /MOD PREPARE 

• /MOD COMMIT 






NOSCH 


X'20' 


IMS scheduling is 
stopped. 


One of the following IMS 
commands was issued for the 
transaction: 
• /PSTOP 
» /LOCK 


15 


1 


Reserved 








16 


2 


Length 




Length (LL) of error 
text, if anv. 


If tnere is error text, it replaces 
all suDsequent sections of tne 
message. 


18 
16 


8 


Error Text 
PSB Name 




iext of tne error 
IMS PSB name. 


vanaole lengtn. fhe error test 
section is applicable only if 
transaction tyoe flag 1 is set to 
Invalid Syntax (X FE ) 

Only oresent if tnere is no error 
text. 


24 




Class 




SMB message class 
for IMS scheduling. 




25 


1 


Current Priority 




Current SMB priority. 







1 


formal Priority 




Normal SMB priority. 








Limit Priority 




SMB limit priority. 




Is 


"""i" 


Enqueue Count 




enqueued. 




30 


"""i" 


Dequeue Count 








32 


2 


Enqueue- Limit 




Enqueue limit count. 




34 


2 


Psocesssrsg Lim<t 
Count 




Processing limit 
count. 




36 


2 


Output Max 
S«-gmont Lc-ngEh 




Tne maximum output 
segment lenath. 




38 


2 


Output Limit of 
Message- Segments 




i ne output limit of 
message segments. 




40 


2 


Parailel Limit 




The PARLIM value 
from TRANSACTION 
statement. 
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Tabie 26. 


Transaction Attributes Segment (continued) 




Byte 


Length Content Vaitse 


Meaning Comments 


42 


1 Region Count 


The number of 






regions in which the 






transaction is 






currently scheduled. 
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Chapter 7, OTMA Callable Interface 



This chapter introduces the OTMA Callable Interface, and describes how to use it. 

The following topics provide additional information: 

• "Introduction to OTMA Callable interface" 

« "Getting Started with OTMA C/l" on page 102 

» "OTMA C/l APIs" on page 105 

• "Codes and Messages Used by OTMA C/l" on page 119 

• "OTMA C/l Sample Programs" on page 128 



Introduction to OTMA Callable Interface 

The IMS OTMA Callable interface (C/l), which became available with IMS Version 
6, provides a high-level interface for access to IMS applications from other z/OS 
subsystems. The interface consists of API calls that are available to a C/C++ 
program. The API calls are used to join the IMS/OTMA XCF group, to connect to 
IMS, to allocate communication sessions, to send IMS transactions/commands, to 
receive output from IMS, to close communication sessions, and to leave the XCF 
group. 

Figure 37 on page 102 provides an overview of the OTMA C/L Shown from left to 
right, in a sample z/OS environment, are sample C and C++ API calls (for example, 
OTMA_OPEM). The API calls pass through an object stub, the SVC interface 
routine, the API (for example, DFSYOPEN), and finally through the XCF group to 
IMS OTMA. 
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Introduction to OTSVfA C/l 



OS/390 Environment 



OTMAjDPEN 

OTMA ALLOC 

OTMS SEND RECEIVE 

OTMA_FREE 

OTMA CLOSE 



-SVC 



SEND and 
RECEIVE 
function... 



Process 
CLOSE 
Function 



Figure 37, OTMA Callable interlace Oven 




The program mat invokes the API calls can be running from an authorized or 
unauthorized library in problem or supervisor state. DFSYCO, a C header file, is 
provided to define the API calls. DFSYCRET, a load module, contains the entry 
points for each API call and is linked with the application program. OTMA C/l uses 
BPE SVC Services to process the API call. 

Benefits :A key benefit of OTMA C/l is that \i is easy to use. 



Other reasons to use OTMA C/l are that it: 

• Extracts out the details of OTMA and XCF 

• Submits IMS transactions and commands 

• Enables programs running from other z/OS subsystems to connect to multiple 
IMSs 

• Calls the APIs from an authorized or unauthorized library 

• Connects to all IMS OTMA releases 



Getting Started with OTIWIA C/l 

The following topics describe the information that you need to begin using the 
OTMA C/l: 

• "OTMA C/l Environment Requirements" on page 1 03 

• "OTMA C/i Migration and Coexistence" on page 103 

• "OTMA C/i Initialization" on page 103 

• "OTMA C/l Security" on page 104 

• "OTMA C/l Restrictions" on page 1 04 
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GTfVfA C/l Environment Requirements 

To initialize and install OTMA C/l, OS/390 Release 3 or above and IMS Version 8 or 
above are required. 

GTfVfA C/l Migratfon and Coexistence 

OTMA C/l requires IMS Version 6 or above for initialization and installation. OTMA 
C/l can coexist with ail OTMA releases. 



RAS criteria, design elements, support plan, and hardware programming support 
remain consistent with IMS Version 6. 



QTfVIA C/l Initialization 

OTMA C/l provides a stand-alone program, DFSYSVIO, that must be run after the 
z/OS IPL to initialize the OTMA C/l. DFSYSVIO invokes DFSYSVCO, one of the 
OTMA C/l modules. DFSYSVCO loads and registers the SVC services by an 
authorized address space running on the same z/OS image as the application 
programs accessing it. 



You must add an entry in the z/OS program properties table (PPT) for the OTMA 
Callable Interface initialization program. The steps for doing this are: 

1 . Edit the SCHEDxx member of the SYS1 PARMLIB data set. 

2. Add the following entry to the SCHEDxx member: 

PPT PGMNAME(DFSYSVIQ) /* PROGRAM NAME - DFSYSVIO */ 

CANCEL /* PROGRAM CAN BE CANCELED */ 

KEY (7) ./* PROTECT KEY ASSIGNED IS 7 */ 

SWAP /* PROGRAM IS SWAPPABLE */ 

NOPRIV /* PROGRAM IS NOT PRIVILEGED */ 

DSI /* REQUIRES DATA SET INTEGRITY */ 

PASS /* CANNOT BYPASS PASSWORD PROTECTION */ 

SYST ./* PROGRAM IS A SYSTEM TASK */ 

AFF(NONE) /* NO CPU AFFINITY */ 

NOPREF /* NO PREFERRED STORAGE FRAMES */ 

3. Take one of the following actions to make the SCHEDxx changes effective: 

Re-IPLthe z/OS system, 
or 

issue the MVS SET SCH- command. 
Related Reading: For additional reading about updating the program properties 
table, see z/OS MVS Initialization and Tuning Reference. 



A sample JCL procedure for running DFSYSVIO is as follows: 

//OTMA EN IT PROC RGN=3000K,S0UT=A, 

// PARM1- 

//* 

//IEFPROC EXEC PGM=DFSYSVIQ, 
REGION--&RGN 

//STEPLIB DD 
// 
//* 

//SYSPRINT DD 
//SYSUDUMP DD 



DISP=SHR,UNTT=SYSDA, 
DSN=1MSVS.SDFSRESL 

SYS0UT---&S0UT 
SYS0UT=&S0UT 
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OTMA C/I Security 

To protect XCF groups from any non-authorized caller use IMSXCF.OTMACI, a RACF 
resource, defined in the RACF facility class for the OTMA C/I. When the RACF 
resource is defined, RACF RACHECK is invoked before OTMA C/I performs a XCF JOIN. 
This method protects the access to XCF, the XCF group, and the member. This 
RACF checking is performed only when a non-authorized caller is using OTMA C/I. 

Additional security characteristics remain consistent with OTMA in IMS 8.1. 

OTMA C/I Restrictions 

These restrictions apply to the OTMA C/I: 

• OTMA C/I must be initialized and installed in IMS 6.1 and above, but OTMA C/I 
can connect to all IMS OTMA releases. 

• Application program languages other than C and C++ are not currently supported 
by OTMA C/I. 

• Ail OTMA calls must be made in the same state (PSW key, supervisor or 
problem state, authorized or non-authorized) as the Qtma_open call. For example: 
If you were authorized when you did the otma_open call, you must be authorized 
for all subsequent calls. 

• The resynchronization feature of IMS OTMA is not supported. 

• IMS command /SECURE OTMA PROFILE, is not currently supported. 

OTMA C/I Hints and Tips 

This section describes several usage tips for the OTMA C/L 

• C/i must be installed in an OS/390 or z/OS environment before it can be invoked. 
If C/I is not installed and invoked, an F92 abend occurs when otma. create or 
otma_open is issued. If C/I is not properly installed, a DFS3911E error message 
occurs. 

• otma_open, otma_openx. otma_send_receive, otma_send_receivex, 
otma...send....async, and otma...receive..async each have an ECB parameter. This 
ECB is posted by the function or by an SRB routine that the function precipitates. 
The caller must check the ECB and wait for it to be posted before inspecting the 
return code and output data. Be sure to initialize the ECB with 0 before passing 
to the C/I call. 

• Each otma_aiioc call creates an independent session for the subsequent 
otma...send....receive call. One of the otma ..alloc calls can be used to specify the 
name of IMS transaction or IMS command to be sent to IMS. The maximum 
length of the transaction name is 8 characters, if no transaction name or 
command is specified in the otma__alloc call, the transaction name, followed by 
one or more blanks, or command needs be specified in the beginning of the send 
buffer of the otma_send_receive call. After the otma__send__receive call, 

otma. ..free is required, except for the IMS conversation transaction. See the 
invocation sample C for sending a conversation transaction. 

• C/i builds the standard LLZZ part of IMS application data format. You do not 
need to worry about the LLZZ at all. 

• To send a multi-segment message to IMS, the send segment list of the 
Gtma__send__receive call must identify the length of each input segment. The first 
element in the segment list specifies the number of the segment. The first 
element is then followed by the length of segment 1 , the length of segment 2, 
and so on. 

• When a multi-segment output message is received, an output segment list is 
provided for the of rna... send. .receive call. The first element in the output segment 
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list contains the number of the output segment. The first element is then followed 
by the length of output segment 1 , the length of output segment 2, and so on. 

• Sample programs (DFSYCSMP) are shipped with IMS. See also "OTMA C/l 
Sample Program #1: Synchronous Processing" on page 129 and "OTMA C/l 
Sample Program #2: Asynchronous Processing" on page 140. 

• C/l can be used to send a protected transaction to IMS by passing a context 
token to the otma....send..receive call. 

• Because some of the C/l calls require the calling program to wait, implementing 
the time-out routine in the calling program is highly recommended to avoid long 
running transactions in IMS and the internal C/l hang. 

• To run the C/l application efficiently, limit the number of otma. open and 
otma_close calls in the application. Also, for all otma_open and otma_create 
calls, try to use the same member name rather than generating a different 
member name for each call. 

• If the size of the output receive buffer specified in the otma..send...receive call is 
too small, the actual data returned is limited by the size of the receive buffer. The 
output can be rejected if a special option, SyncLevell , is specified in the 
otma_alloc call. However, if the size of the output receive buffer is too small for 
the otma....receive. async call, C/i always rejects the output. 

« C/l can support various program-to-program switches in IMS. See "OTMA 
Program-to-Program Switch Processing" on page 56 for more information. 

« C/l could return a bad return code to inform the caller about an abnormal 
condition. Logging or saving the bad return code for debugging purpose is 
recommended. 

• The otma_send_receive call sends an OTMA send-then-commit message with 
synclevel=none to IMS. The caller can set a synclevel=confirm for 

otma. send... receive. 

• When an input RRS context token is given in the otma_send_receive call, the 
syncievei is then changed to SYNCPT to support the protected transaction. 

• For complex program-to-program switches in IMS, a send-then-commit input 
message could result in a commit-then-send output message instead of the 
expected send-then-commit output message. C/l works in this special scenario. 
See "OTMA Program-to-Program Switch Processing" on page 58 for more 
information on program-to-program switches. 

• The otma_send_async call sends an OTMA commit-then-send message to IMS. 

• The otma. .receive., async call receives an OTMA commit-then-send output 
message from IMS. 

• C/l does not support either the OTMA resync protocol or the OTMA security 
PROFILE option. 

OTMA C/l APIs 

This topic describes all of the OTMA callable interface application programming 
interfaces (APIs). 

Using the Header File DFSYCO.H: 

The header file included in the API calling program declares each API invocation 
and variables used for the invocation. 

For a C/C++ program using OTMA Callable interface, the C/C++ header file, 
DFSYCO.H, needs to be included in the C/C++ program. 
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Load Module DFSYCRET: 

The object stub, DFSYCRET, receives all the AP! invocations and issues a SVC call 
to perform the requested function. The object stub needs to be available during the 
link-editing of the API invoking program. DFSYCRET can be found in SDFSRESL or 
ADFSLOAD data sets. 



The functions implemented by the API are: 
CALL FUMCTSOM 
otmacreate 



otma_open 

otmaopenx 



otma__a1 1 oc 
otmasend receive 

©tina_send_receivex 



Creates storage structures to s 
communications but does not establish a 
connection with IMS. 

Establishes a connection with IMS. Issue an 

otnm create prior to establishing an otma_operi call. 

Provides the same function as otma_open API, with 
an added parameter to specify OTMA Destination 
Resolution User (DRU) exit name routine and 
special options. 

Creates an independent transaction session. 

Sends to IMS and passes parameters for receive 
functions. 

Provides the same function as otma_send_receive 
API, with an added parameter to pass OTMA user 



Gtma_sesid_a$ync 

otma_receive_async 

otma_free 

otma close 



Sends input (transaction or IMS command) only to 
IMS. 

Receives unsolicited or queued output from IMS. 
Releases the independent transaction session. 
Ends the connection with IMS. 



The following topics provide additional information: 
"Using otma_create" 
"Using otma_open" on page 108 
"Using otma_openx" on page 109 
"Using Qimajalloc" on page 110 
"Using otma_send_receive" on page 111 
"Using otma_send_receivex" on page 114 
"Using otma_send_async" on page 114 
"Using otma_receive_async" on page 117 
"Using oimajree" on page 118 
"Using otma_close" on page 119 



Using otma_create 



Description 

The otma_create API is to allocate storages for XCF and IMS communications. 
After the call, an anchor will be returned. The anchor must be used for the 
subsequent calls. Invoking otma_create is not required. During the otma__open, 
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OTMA C/l will allocate storages for communication, if it detects that otma.create 
has not been called, if otma_create is invoked first, the same input parameters 
need to be used again for the subsequent otma ...open call. 

Invocation 

Called by the client in TCB mode. 

Input 

*scb Pointer to the next event control block. 

*group_jiame Pointer to the string containing the XCF group name. (char[8i) 

*member„!ia!T?e 

Pointer to the string containing the XCF member name for this 
member. (char[16]) 

*partrser__rsame 

Pointer to the string containing the XCF member name for IMS. 
(char[18j) 

*sessiorss Number of parallel sessions that are intended to be supported with 
IMS. Long integer from 001 to 999. 

*tpipe_prefix First 1 to 4 characters of the tpipe names. (char[4i) 

For more information on OTMA tpipe naming conventions, see 
"OTMA Naming Conventions" on page 14. 

Attention: For the input fields group .name, member .rjame, and partner .rsame, 
all XCF names that are pointed to must be left justified, filled with blanks, and 
consist of legal upper case EBCDIC characters. If any of those naming rules are 
violated, underlying XCF errors will be reported. 

Output 

*anchor Pointer to the anchor word. 

Tetrsn Pointer to the return code structure. 

C-Language Function Prototype 

otma..create( 



otma_anchor_t 




[ou 


otma retrsn t 




[ou 


ecb_t 


*ecb, 


[in 


otma grp name t 


*group_name, 


[in 


otma_clt_name 




[in 


otma_srv_name 


*partner_name, 


[in 


signed long int 




[in 


unsigned char 


*tpipejname) ; 


[in 



Return Values (re value) 

The rc and reason are valid after ECB has been posted. For the complete 
description of each error, see Table 27 on page 121 . 

0 The call was completed successfully. 

8 User error. 

12 Storage obtain failure. 
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Using otma_open 

Description 

The calier must caiS otma_open to connect when IMS is available. The caller must 
wait on the ECB, that is posted when the connection is completed or when the 
attempt has failed. When IMS is not up or OTMA is not started the attempt will fail. 

The caller can cancel the attempt to connect with IMS by issuing an otma_dose call 
at any time. The ECB will be posted accordingly. 

If IMS fails after this connection is established, any call to a function interface will 
receive a return code to indicate that IMS is no longer listening for messages. If 
IMS resumes before a close is performed, the connection will be reestablished 
without any action from the client. The otma_c1ose and otma_ppen interfaces may be 
called again to reestablish communications with IMS. All existing conversations will 
have been terminated. This implementation does not use OTMA Resynchronization 
Protocol. 

An extended version of the otma_open API, which is called otma_openx, provides 
extended functionality. See "Using otma..ppenx" on page 109 for more details about 
the otma_openx API. 

invocation 

Called by the client in TCB mode. 

Input 

*artchor Pointer to the anchor word. If otma_create is not used to set up the 

anchor environment, the anchor word must be initialized with a 
zero. 

*groisp„.riame Pointer to the string containing the XCF group name. (char[8]) 

*membsr_narrse 

Pointer to the string containing the XCF member name for this 
member. (char[16j) 

*partner__name 

Pointer to the string containing the XCF member name for IMS. 
(char[16]) 

*sessiorss Number of parallel sessions that are intended to be supported with 
IMS. Long integer from 001 to 999. 

*tpipe__prefix First 1 to 4 characters of the tpipe names. (char[4]). 

For more information on OTMA tpipe naming conventions, see 
"OTMA Naming Conventions" on page 14. 

Attention : For the input fields groupjname, member_name, and partrier__rjame, 
ail XCF names that are pointed to must be left justified, filled with blanks, and 
consist of legal upper case EBCDIC characters. If any of those naming rules are 
violated, underlying XCF errors will be reported. 

Output 

*anchor Pointer to the anchor word to receive the address of global storage, 

*retrsr« Pointer to the return code structure. 
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*scb Pointer to the event control block to be posted when the open 

completes. 

C-Language Function Prototype 

otma_ open ( 









otma retrsn t 




[out; 


ecb_t 


*ecb, 


[out; 


otma grp name t 


*group_name. 




otma clt name t 


member _ name, 




otma_srv_name_t 












unsigned char' 


*tpipe_naine); 





Post Codes 

The caller of the OPEN routine must check the ECB that was provided to OPEN, if 
this ECB is not already posted, the caller must wait for this ECB (for the OPEN 
protocol to complete). 

0 XCF OPEN completes successfully. 

4 IMS is not ready. Try again later. 

8 Your XCF group and member are already active. 

12 A system error occurred. 

Return Values (re vaiue) 

The rc and reason are valid after ECB has been posted. 

0 XCF JOIN was successful, client-bid was sent, and acknowledgment 

received. For the complete description of each error, see Table 27 on page 
121. 

4 IMS is not ready. Try again later. 

8 Your XCF group and member are already active. 

12 A system error occurred. 

Using Gtma„©penx 

Description 

The otma__openx API has the same functionality as the otma_open API, with the 
following extended features: 

* The ability to specify an OTMA DRU exit routine 

• Added capability for future enhancements to the API 

invocation 

Same as for the otma_ppen API. 

input 

Same as for the otma_ppen API, with the following additional parameters: 

*irrss_jdru__jsarne 

Pointer to the string containing the user-defined OTMA Destination 
Resolution User Exit Routine. 

*speciaS„optio!is 

Pointer to an area codifying non-standard options. Currently, there 
are no special options supported. Specify a NULL for this 
parameter. 
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Output 

Same as for the otma_open API. 

C-Language Function Prototype 

otma_openx ( 





♦anchor, [out] 


otma retrsn t 


*retrsn, [out] 


ecb_t 


*ecb, [out] 


otma grp name t 




otma_c!t_name_t 


*mesnber_name, [in] 




♦partner name, [in] 




♦sessions, [in] 


tp'ipejjrrxj; 


*t f .ipe_prefix, [in] 


otma dru name t 


*ims_dru_name, [in] 


otma.profile4..t 


*specia1_options) ; [in] 



Post Codes 

Same as for the otma_open API. 

Return Values (re value) 

Same as for the otma_open API. 



Using otma_alloc 



Description 

The otma_a]1oc API is called to create an independent session to exchange 
messages. 

Invocation 

Called by the client in TCB mode. 

Input 

*anchor Pointer to anchor word that was set up by otma_open. 

*username Pointer to string holding the RACF username for 
transaction/commands. 

For calls from authorized programs, the input username is trusted 
and passed to IMS. For calls from unauthorized programs, OTMA 
C/l invokes a RACF call with the current ACEE context to obtain the 
username. The input username, if any, will be ignored. A NULL can 
be specified for callers from unauthorized programs. 

transaction Name of IMS transaction or command to be sent to IMS. 

If the IMS command entered is longer than eight characters, the 
first eight characters of the command can be provided in this 
parameter. The rest of the characters of the command need to be 
provided in the beginning of the send buffer of the subsequent 
otma_send_receive API. 

if this parameter is left blank, then the IMS transaction name or 
command must be specified (left aligned) in the beginning of the 
send buffer of the subsequent otma_serid_receive API. 

*prfrsame Pointer to a string holding the RACF group name for 
transactions/commands. 
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*speciaL.optiG!is 

Pointer to the processing options for the subsequent 

otEiia send receive or otma_send_receivex API call. The supported 

processing options include: 

Bit 0 SyncOnReturn - with this option, IMS is asked to process 
the message without the RRS context token; in this case, 
the user ID is obtained when RRS CTXRDTA is invoked. 

Bit 1 SyncLeveh - with this option, OTMA send_then_commit 
sync level 1 is used instead of sync level 0, which is the 
default for OTMA C/l. Refer to the DFSYCO header file for 
additional information. 

Output 

*retrssi Pointer to return code structure. 

*sess!Oii_harid!e 

Pointer to session handle that uniquely identifies the session for the 
subsequent otma_send_receive. 

C-Languag© Function Prototype 

otri:a..al1oc( 



otma_anchor_t *anch 


or, [in] 




■sn, [ou1 




ionjiandle, [oul 


otma profile t *spec 


ial options, [in] 


tran name t *tran 


saction, [in] 


racf_uid_t *user 


•name, [in] 


racf_prf_t *prfna 


me); [in] 



Return Values (re value) 

The rc and reason are valid after ECB has been posted. For the complete 
description of each error, see Table 27 on page 121 . 

0 Success. 

4 Session limit reached. 

8 Null anchor. 



Using otma_send_receive 

Description 

The otma_send_receive API is invoked to initiate a message exchange with IMS. 
The caller gives buffer definitions for both send and receive. Both send buffer and 
receive buffer information is provided. By providing receive information at the same 
time as send there are no unexpected messages from IMS, greatly simplifying the 
protocol. When the reply arrives from IMS the ECB wil! be posted. All the work of 
buffer management is handled in the message exit routine. 



An extended version of the otma_send_receive API, which is called 

otma_send_receivex, provides extended functionality. See "Using 

otma send receivex" on page 114 for more details about the otma_send_receivex 

API. 



Invocation 

Called by the client in TCB mode. 
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Input 
*anchor 



Pointer to anchor word that was set up by otma_open. 



*sessiorj„ha!idle 

Pointer to session handle for tpipe returned by otma__alloc. 

*lterm Pointer to 1 term name field. On input is passed to IMS. Will be 

updated on output to Iterm field returned by IMS. Can be blank in 
both cases. 

*modrsame Pointer to MODname name field. On input is passed to IMS. Will be 
updated on output to MODname field returned by IMS. May be blank 
in both cases. 

If the input modname is DFSM01 . DFSM02, or DFSM05, it will be 
treated as blanks. 

*seod„ buffer Pointer to the data to be sent to IMS. When a NULL is specified for 
the transaction parameter, the client code must provide the 
transaction name or command, and a blank, to the data in this 
buffer when sending to IMS. 

*seod.jength Length of send data. 

*sersd .segment Jsst 

An array of lengths of message segments to be sent to IMS. First 
element is count of following segment lengths. Optional: If a single 
segment is to be sent, either the first element or the address of the 
array can be zero. 



*recel¥e__biiffer 



Pointer to buffer to receive reply message from IMS. 

*reeeivejength 

Length of buffer available to receive message. 

*recslve _segmerst__jist 

An array to hold the number of segments sent by IMS. First 
element must be set as the number of elements in the array. 
Optional: if a single segment is to be received, either the first 
element or the address of the array can be zero. In which case all 
segments will be received contiguously without indication of 
segmentation boundaries. 



*GGrjtext_jd 



Output 
*retrsr* 
*ecb Event 



Null or Distributed Sync Point Context ID from RRS. 

• For an authorized caller, OTMA C/l passes the Context ID 
directly to IMS and does not validate the Context ID data. 

• For an unauthorized caller, OTMA C/l invokes the CTXSWCH 
call to disassociate the token and to validate if the token is 
current for a task. When OTMA C/l receives a response from 
IMS, it switches the context back onto the task before returning 
control to the caller. 



Pointer to return code structure. 

Control block to be posted when the message exchange is 
complete. 
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*rsceivsd_jersgth 

Field to receive length of data received to recei ve_buffer. Should 
be equal to the sum of the segment lengths. 

*reeeire_segmenitjist 

An array of lengths of [message segments received from IMS. First 
element is count of following segment lengths and must be set by 
client to indicate maximum length of array. It will be modified by 
receive. 

'errorjnrsessage 

Address of the pointer to the error message field, it is provided by 
the user to receive error or informational messages from IMS. if the 
post code returns a 20, then this field will contain data. 

OLanguage Function Prototype 



sessjiand!e_t 
! term_name_t 
mod name t 



*send_buffer, 
*send_ length, 
*send_seg_l ist ; 



char 



'segment too lar 



Post Codes 

0 Normal completion. 

8 No anchor/bad session 

12 Send failed. 

18 Receive has been cancelled. 

20 Error from IMS. 



Return Values (re value) 

The rc and reason are valid after ECB has been posted. For the complete 
description of each error, see Table 27 on page 121 . 



0 



12 
18 



Normal completion. 

No anchor/bad session handle/segment too large. 
Send failed. 

Receive has been cancelled. 
Error from IMS. 
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Using otma_send_receivex 

Description 

The otma_send_receivex API has the same functionality as the otma_send_receive 
API, but adds the extended ability to pass OTMA user data. 

Invocation 

Same as for the otma_send_receive API. 

Input 

Same as for the otma_send_ receive API, with the following additional parameter: 

*otrT3a__user_data 

Pointer to the OTMA user data. The OTMA user data field can 
contain any user data that is used to identify the user input, or to 
correlate input with output, if a value is specified in this field, the 
data is sent to IMS. IMS user exits DFSYiOEO and DFSYDRUO can 
read or change the data. The data is returned to the user if the 
otma_receive_async API with otma_user_data is issued. 

If there is no OTMA user data, specify a NULL for this field. 

Output 

Same as for the otma_send_receive API. 

C-Language Function Prototype 



otma anchor t 


*anchor, 


[in] 


otma retrsn t 




[out 


ecb_t 


*ecb. 


[out 


sess handle t 




[in] 


lterm_nairte_t 


*Tteriii, ~ 


[in/ 






[in/ 




*sercd_buffer, 


[in] 






[in] 


dataj eng_t 


*send~segwnt_list, 


[in] 


char 


*receive buffer, 


[in] 


data_l eng_t 


*receive_iength, 


[in] 




*recei ved_l ength, 


[out 


dataj eng_t 




[in/ 


context_t 


*context_id, 


[in] 




*error_message, 


[out" 


ot!na_user_t 


*otma_userdata) ; 


[in/ 



Post Codes 

Same as for the otma_send_ receive API. 

Return Values (re value) 

Same as for the otma_send_receive API. 

Using otma„send„async 
Description 

The otma_send_async API is invoked to send a transaction or command to IMS. 
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Restriction: This AP! cannot be used to submit an IMS fast path transaction, a 
protected transaction (the transactions with RRS context IDs), or an IMS 
conversational transaction. For these three types of transactions, use the 
otma_send_receive AP! instead. 

invocation 

Cailed by the client in TCB mode. 

Input 

*arschor Pointer to anchor word that was set up by otnia_open. 

*iterm Pointer to 1 term name field. If there is no input 1 term, specify a 

NULL. 

*modname Pointer to MODname name field. If there is no input MODname, specify a 
NULL. 

*otma__i!ser„data 

Pointer to the OTMA user data. This 1022-byte field is optional. The 
OTMA user data field can contain any user data that is used to 
identify the user input, or to correlate input with output. If a value is 
specified in this field, the data is sent to IMS. IMS user exits 
DFSYIOEO and DFSYDRUO can read or change the data. The data 
is returned to the user if the otma_receive_async API with 
otma_user_data is issued. 

If there is no OTMA user data, specify a NULL for this field. 

*prfname Pointer to string holding the RACF group name for 

transactions/commands. This parameter is optional. If there is no 
input RACF group name, specify a NULL. 

*serjd„_biiffer Pointer to the data to be sent to IMS. When a NULL is specified for 
the transaction parameter, the client code must provide the 
transaction name or command, and a blank, to the data in this 
buffer when sending to IMS. 

*send„Jersgth Length of send data. 

*semd_segmentj!st 

An array of lengths of message segments to be sent to IMS. This 
parameter is required for multi-segment input messages. If 
specified, the first element needs to contain the count of total input 
segments. This field is optional for single segment input. If a single 
segment is to be sent, either the first element or the address of the 
array can be zero. 

'special ...options 

Pointer to an area codifying non-standard options. Currently, no 
special options are supported. Specify a NULL for this parameter. 

*tpipe_name Pointer to OTMA tpipe name field. This name must be different from 
the tpipe name specified for the ot.ma_create and otma_open APIs. 

^transaction Name of IMS transaction or command to be sent to IMS. 

If the IMS command entered is longer than eight characters, the 
first eight characters of the command can be provided in this 
parameter. The rest of the characters of the command need to be 
provided in the beginning of the send buffer. 
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If NULL or blanks are specified in this parameter, OTMA C/l expects 
the user to include the IMS transaction name or command in the 
beginning of the send buffer. 

*i!semarrse Pointer to a string holding the RACF username for 
transaction/commands. 

For calls from authorized programs, the input username is trusted 
and passed to IMS. For calls from unauthorized programs, OTMA 
C/l invokes a RACF call with the current ACEE context to obtain the 
username. The input username, if any, will be ignored. A NULL can 
be specified for callers from unauthorized programs. 

Output 

*ecb Event Event control block to be posted when IMS receives or rejects the 
input. 

*errar_message 

Address of the pointer to the error message field. It is provided by 
the user to receive error or informational messages from IMS. If the 
post code returns a 20, then this field will contain data. 

*retrsrj Pointer to return/reason code structure. If IMS OTMA rejects the 

input, the NAK code and its associated reason code are available in 
OTMA C/l reason codes 2 and 3. See "OTMA Return Codes" on 
page 69 for an explanation of the NAK code. 

C-Language Function Prototype 

otnKt_senci_async( 

otma_anchor_ 

ecb_t 

tpipe_na!Tie_t 
tran_name_t 
racf_uidj: 
racf_prf_t 
1 term_name_t 
mod_name_t 
otma__iise 

char 

dataj eng_t 
data_i eng_t 

Post Codes 

0 Normal completion. 

8 Invalid input. 

12 Input failed. 

16 Input cancelled (IMS is down or OTMA is stopped). 

20 Error or information message from IMS. 

Return Values (re value) 

The rc and reason are valid after ECB has been posted. For the complete 
description of each error, see Table 27 on page 121 . 

0 Normal completion. 

116 Open Transaction Manager Access Guide and Reference 



t *anchor, 



: *otma_userdata, 

*send_buffer, 
*sendjength, 
*send_segment_l i st [] 
*error_message, 
*special__options) ; 
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6 No anchor/bad input. 

12 Send failed. 

16 Input cancelled (IMS is down or OTMA is stopped). 

20 Error or information message from IMS. 

Using otma_receive_async 

Description 

The otma_receive_async API is invoked to receive an IMS output message or an 
unsolicited message. The caller provides the buffer definitions to receive the IMS 
message. When the IMS message arrives, the ECB is posted. 

invocation 

Called by the client in TCB mode. 

Input 

*arjchor Pointer to anchor word that was set up by otma_open. 

*tpipe....name Pointer to OTMA tpipe name field. This name must be different from 
the tpipe name specified for the otma_create and otma_open APIs. 

receivejength 

Length of buffer available to receive message. 

Output 

*ecb Event Event control block to be posted when IMS receives the reply. 

*error„ message 

Address of the pointer to the error message field. It is provided by 
the user to receive error or informational messages from IMS. If the 
post code returns a 20, then this field will contain data. 

*lterm Pointer to 1 term name field. Can be updated with 1 term value that 

is returned by IMS. 

*modrsame Pointer to MODname name field. Can be updated with MODname value 
that is returned by IMS. 

*otrrsa„i!ser„data 

Pointer to the OTMA user data. This 1022-byte field is optional, if 
the field is specified and IMS returns the OTMA user data, the data 
is passed back to the caller. 

The OTMA user data received is either provided in the 
otma_send_async API or created by the IMS DRU exit DFSYDRUO. 

*rece!ve__buffer 

Pointer to buffer to receive reply message from IMS. 

'received Jersgth 

Field to receive length of data received to receive_buffer. Should be 
equal to the sum of the segment lengths. 

*reeeire_segmenitjist 

An array of lengths of message segments received from IMS. The 
client must set the first element to indicate the maximum number of 
message segments that can be received. After all the segments are 
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received, the first array eiement indicates the actuai number of 
segments received, and the rest of the array elements indicate the 
length of each segment received. 

*retrsm Pointer to return/reason code structure, 

*speciaLoptsons 

Pointer to an area codifying non-standard options. Currently, no 
special are options supported. Specify a NULL for this parameter. 

C-Laoguage Function Prototype 

~otma__anchor_t *anchor, [in] 
otina_retrsri_t *retrsn, [out" 
ecb t *ecb, 



1 te rename J: *lterrn, [out] 
mod_name_t *modnaine 5 [out] 

otma_user_t *otma_userdata, [out] 

char *receive_buffer, [out] 

datajeng_t *receivejength, [in] 

data_leng_t *received_l ength, [out] 

dataj eng_t *recei ve__segment_J i st [] , [i n/out] 

void *special_options); [in] 

Post Codes 

0 Normal completion. 
12 Receive failed. 

Return Values (re value) 

The rc and reason are valid after ECB has been posted. For the complet 
description of each error, see Table 27 on page 121 . 

0 Normal completion. 

8 No anchor/bad session handle/segment too large. 
12 Send failed. 



Using otma_free 



Description 

The otmajree API is called to free an independent session created by otma__al loc. 

Invocation 

Called by the client in TCB mode. 

Input 

*arschor Pointer to anchor word returned by otma_ppen. 

*sessiorL_handte 

Pointer to session handle returned by otma_anoc. 

Output 

*retrsrj Pointer to return code structure. 

*session_haridfe 

Pointer to session handle will be nulled by otma_f ree. 
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C-Language Function Prototype 

otma anc:hor__t *anchor, [in] 
otsna^YetrsrTt *retrsn, [out] 
sess_hancMe_t *session_hand1e) ; [in/out] 

Return Values (re value) 

The rc and reason are valid after ECB has been posted. For the complete 
description of each error, see Table 27 on page 121 . 

0 Success. 

4 Not allocated session. 

8 Incorrect anchor. 

Using otma_close 

Description 

The otma__c1ose API is called to free storages for communication and to leave XCF 
group. This function may be called when communications are in flight or an open is 
processing. In these cases all relevant ECBs will be posted with a canceled post 
code. 

Invocation 

Called by the client in TCB mode. 

Input 

*anehor 

Pointer to anchor word returned by otma_open. 

Output 
*anchor 

Pointer to anchor word returned by otma_ppen. 

Tetrsn 

Pointer to return code. 

C-Languag© Function Prototype 

otma_c1ose( 

otrw__anchor t *anchor, [in/out] 
otiria_retrsn_t *retrsn); [out] 

Return Values (rc value) 

The rc and reason are valid after ECB has been posted. For the complete 
description of each error, see Table 27 on page 121 . 

0 Success. 

4 Null anchor. 

8 Cannot leave XCF group. 



Codes and Messages Used by OTMA C/l 

I The OTMA C/l uses a number of specific messages and codes. Detailed 

I information is provided in the following topics: 

i • "OTMA Post Codes" on page 120 

i * "OTMA Return Codes" on page 120 
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I • "OTMA Error Messages" on page 127 

OTMA Post Codes 

The asynchronous nature of OTMA message delivery and communication state 
change requires that the program that uses the OTMA C/I use Event Signaling 
methods. The functions otma_open and otma_send_receive are asynchronous, the 
other APIs are not. 

The otma__open, otma__oper>x, otma_send_receive, otma_send_receivex, 
otma_send_async, and otma_receive_async APIs each have an ECB parameter. This 
ECB is posted by the function or by an SRB that the function precipitates. The 
caller of otma_open, otnia_openx, otma_send_receive, otma_send_receivex, 
otma_send_async, and otma_receive_async functions must check this ECB and wait 
for it to be posted before releasing or inspecting any of the output fields mentioned 
in the API, except for the return code in the return code structure. The return code 
from ail six functions indicates failure to initiate communications with a non-zero 
value. The ECB has the same value in these cases. 



The g 


eneral meanings of the POST codes are as follows: 


0 


Data transfer or state change expected is completed. 


4 


Transient problem detected. Try again later. 


8 


User error. 


12 


System error. 


16 


Client or XCF has aborted the function. 


20 


Error from IMS. 



OTMA Return Codes 

The return code structure consists of a return code that indicates the status of a 



request 






0 


Function completed normally. 




4 


Transient problem detected. Try ag; 


ain later. 


8 


User error. 




12 


System error. 




16 


Function cancelled. 




20 


Error from IMS. 





The return code is part of a data structure used by all the API calls and is the post 
code found in any posted ECB. All numerical values are in decimals. 

Four reason code fields are available. 
Reason 1 

Indicates what area in the OTMA client API reported the error. The value 
depends on the function that was called and is listed in Table 27 on page 
121 . All numerical values are in decimals. 

Reason 2, Reason 3 

Provides additional information about the problem. All numerical values are 
in decimals. 
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Reason 4 

Indicates the API that was issued. 

A vector of reason codes describes the details of any failed or partial result. The 
meanings are specific to the function and are described in Table 27. 

Tab < 2' ds-'St "ibes O' MA C/l return codes and reason codes by function. The 
desoi'Dtion of eaon fjnotion includes the return code {in decimal), four possible 
rea;ei: co : s [\x decirrah and a general description. 



Table 27. OTMA C/l Return Codrs ana Rejson redes by Function 



Function 


Return 

Code 

(Decimal) 


Reason 1 
(Decimai; 


flea so ei 2 
(Docima!) 


Reason 3 
(Decimal) 


Reason 4 
(Decimal) 


Description 


CREATE 


0 








1 


Normal completion. 




8 


4 






1 


fhe .st is -of-allowec to ,?e OTMAl-I 
because the user is not permitted to use 
fhe "AU IVI^XCf OfMACI reso,r;e 




8 


20 






1 


OTMA C >vas used in CS'330 -2 o 
beiow, 0 f MA C/l should be used on 
OS/390 P.3 or above. 




8 


28 






1 


1 he session number that is specified is 
greater tnan the maximum number 
allowed f 999). 




12 


12 


BPESVC 

return 

code 




1 


The OTMA C/l service call was rejected 
bv the BPESVC service. See "BPE 
Codes in IMS Version 9: Messages ana 
Goa&s. Voluivs 1 to: lisore information on 
BPESVC return codes. 




12 


800 






1 


Storage obtain failure. 


OPEN and 
OPENX 


0 








2 


Normal completion. 




0 


1xx 


xcf ixcjoln 


xcf ixcjoln 


2 


Member state changed. For more 
information, see OS/390 MVS 
Programming: Syspiex Services 
Reference- 




4 


80 


xcf ixcjoln 


xcf ixcjoln 


2 


IMS OTMA Is not started, an invalid XCF 
group name was specified, or an invalid 
XCF member name was specified. Try 
again later. Server member is not active. 
For more information, see OS/390 MVS 
Programming: Syspiex Services 
Reference. 




8 


0 


xcf 

ixcquery rc 


xcf 

Ixcquery 
rsrs 


2 


Your member name is already active. For 
more information, see OS/390 MVS 
Programming: Syspiex Services 
Reference. 




8 








2 


The user is not aiiowed to use OTMA C/l 
because the user is not permitted to use 
the RACF iMSXCF.OTMAC! resource. 
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Table 27. OTMA C/l Return Codes and Reason Codes by Function (continued) 



Function 


Return 

Code 

(Decima!) 


Reason 1 
(Decimai) 


Reason 2 
(Decimal) 


Reason 3 
(Decimal) 


Reason 4 
(Dec: ma') 


I Description 




8 


8 






2 


■ i ne user is not anowed to soecifv the 
i input anchor. Tne input anchor shouid oe 
i returned from the otrna create APi or a 
: new anchoi should be initialized with 0, If 
i the input anchor is correct, ensure tnat 
the mpu* a cup rvsr^ ♦he )ui nvrcnr 
i name, ana the input partner name are the 
i same as the names specified in the 
I ot:iia__create APi. 




8 


12 






2 


i Client Did is refused. 




8 


16 








i Client Did is rerusea due to security 
■ failure. 




8 


20 






2 


\ OTMA C/l was used in OS/390 P.2 or 
■ Delow. OTMA C/i should oe usea on 
I OS/390 R3 or above. 














i i ne session nurribei that is specified is 
i greater than tne maximum numcer 
i allowed (999). 








xcf ixcjoin 


xcf ixcjoin 
rsn 




■ Member is in an unknown state. Foi mo^e 
i information, see OS/390 MVS 
i Programming: Sysplex Services 
i Heference. 






10x 


xcf ixcjoin 
rc 


xcf ixcjoin 
rsn 




[Join sysplex failed. For more information, 
i see US/3.90 MVS programming: Sysplex 
i Seri'ices Reference. 




12 


11x 


xcf ixcjoin 


xcf ixcjoin 


2 


■Join local failed. For more information. 
■ see QS/*jQQ MVS Programming. Sysplex 
i Services Heference. 




12 


12 


BPESVC 
code 




2 


i Tne OTMA C/i service call was reiectea 

■ oy the BPESVC service. Se^ Br^L 

i Codes in IMS Version 9: Messages and 

■ Coaes. Volume 1 for more information on 

■ BPESVC return cooes. 




12 


400 


xcf 

ixcquery rc 


xcf 

ixcquery 
rsn 


2 


i Ouerv syspiex faned. For more 

i information, see z'OS MVS Programming: 

i Sysplex Services Guide. 




12 


800 


0 


0 


3 


i Getmam failure. 


ALLOC 


0 


0 


0 


0 


5 


i Norma!. 




4 


12 


8 


0 


5 


i Tne OTMA C/i cannot dynamically 

i allocate a session for one of tne following 

i reasons beiow: 

i • i he number of existing sessions is 
i already at maximum, or 
i * C/l cannot obtain any fiee stoiage fiom 
i suboool 230 for the session usacse. 




8 


4 


0 


0 


5 


1 Null anchor. 




8 


16 






5 


i Incorrect input anchor. 




8 


20 






5 


A'rastciion are or command was 
i entered. However, it was not left-iustitied. 
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Tabie 27. OTMA C/l Return Codes and Reason Codes by Function (continued) 



Function 


Return 

Code 

(Decimal) 


(Decimal) 


{Decima!) 


Reason 3 
(Deeimai) 


(Decimal) 


Description 




8 


24 


Caller's 
new state 


Caller's 
old state 


5 


Caller changed the program state or key 
- see reason codes 3 and 4. Program 
state and key should remain the same ror 
all API calls. 




12 


12 


BPESVC 
return 






The OTMA C/l service call was rejected 
by the BPESVC service. See "BPE 
Codes'' in IMS Version Qi Messages and 
Codes, Volume 1 for more information on 
BPESVC return codes. 


SEND 
RECEIVE 
and SEND 
RECEIVEX 


0 


0 






7 


Normal. 




0 








7 


Conversational, 






44 


Maximum 
number of 
multi- 
segments 
specified 
in the 
receive 
segment 
list 


Actual 
number of 
multi- 
segments 
sent from 
IMS 


7 


The first array element of the receive 
segment list specities the maximum 
number of multi-segments thai can be 
receivea from IMS, 

if IMS senas more multi-segments than 
the number specified in the receive 
segment list, the iasr element in the 
receve scg nc ^t st will induce t -■sze 
of the rest of tne multi-segments. All of 
the multi-segments will be storea in tne 
receive buffer. 




0 


48 


Length of 
fne receive 
Dutfer 
specified. 


Length ot 

bufrer 
neeaed to 
ccta all 
of the 
output. 


7 


f he t \7n w the b. tei is tc o short 1 lie 
actual data :eturneQ ss ssmsteo by the size 
or the receive buffer. 




8 








7 


No anchor. 




8 


8 








Bad session handle. 




8 


12 


Session 
state 




7 


Invalid session state. 




8 


16 






7 


Incorrect input anchor. 




8 


24 


Caller's 
new state 


Caller's 
old state 


7 


Caller changed the program state or key 
- see reason codes 3 and 4. Program 
state and key should remain the same for 
all API calls. 




8 


32 


Segment 
number 


Maximum 
Size 


7 


Segment is too large. 




8 


40 






7 


Buffer!=segments, 
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Table 27. OTMA C/l Return Codes and Reason Codes by Function (continued) 



Function 


Return 

Code 

(Decima!) 


Reason 1 
(Decimai) 


Reason 2 
(Decimal) 


Reason 3 
(Decimal) 


Reason 4 
(Dec: ma') 


Description 




8 


44 


The 

maximum 
number of 
multi- 
segments 
specified 
in the 
receive 
segment 
list 


Actual 
number of 
multi- 
segments 
sent from 
IMS. 


7 


■ ne client specified SyncLeveH in tne 
special option parameter of the 
otma alloc API. C/l rejected the IMS 
outout oecause the size of the receive 
segment list is too small. 




8 


48 


Length of 
receive 
buffer 
specified. 


Length of 
receive 
buffer 
needed to 
include all 
the output. 


7 


Tne size of the receive buffer is too snort. 
CnecK the receive_Dutfer and 
te;eivejength xirancm and rorrccl I ■> 
application program ro use the bufrer size 
r -'turner in rcaso och ^ This ->rror 
occurs only wnen the client specifies 
Synci-dveM in the special option 
oarameter of the otma alloc API. 




8 








7 


Either input Iterm or modname is NULL, 
Tne Iterm and modname fselos ase 
upoateo on output so they cannot be set 
to NULL on input. Leave these tieias 
plan* if tney are not to be used. 








rrs ctxswc 
rc 






Switch off failed. For more information, 
see US/3.90 MVS programming: 
Resource Hecoverv. 




8 


60 






7 


Input Native token. 




8 


64 






7 


Non-current token. 




8 


68 






7 


Tne input send length is 0 or less than 0. 




8 


80 








Input rejected. An attempt was made to 

j i -■to inpu* message br a 
non-conversational transaction on an 
Mjlina sessnn "Mndlc Yc mus* free 
the previous sess-on handle bv issuing an 
OlMAJ HI I and then irs.* =m 
OTMA ALLOC for the new transaction. 




12 


8 


Send 
return 


Send 


7 


Send failed. Reason 2 and Reason 3 are 
set bv XCF IXCMSGO. Refer to SYSplex 
Services Refesence (IXCJOIN) for the 
Return ana reason cocse definitions. 




12 


12 


BPESVC 
code 




7 


i ne ul MA C/l service call was reiectea 
oy the BPESVC seiv-ce. See BPE 
Codes in IMS Version 9: Messages and 
Codes, Volume 1 for more information on 
BPESVC return coaes. 




12 


16 


rrs ctxswc 




7 


Switch c Mai! •'d F Dr more ^>rati> 
see z'OS V1R4.0 MVs Programming: 
Resource Hecoverv 




12 


20 


Session 
state 


Session 
correlator 


Session 
number 


Invalid session state while processing a 
multi-segment messaae. 
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Tabie 27. OTMA C/l Return Codes and Reason Codes by Function (continued) 



Function 


Return 

Code 

(Decimal) 

16 


Reason 1 
(Decimal) 


Reason 2 
(Decimat) 


Reason 3 
(Decimal) 


Reason 4 
(Decimal) 


Description 

Receive has been cancelled by IMS. 
Either IMS is down, or OTMA is stooped. 




20 


NAK code 


NAK 
reason 






l the IMS ejected t i inp^t ne'sfage oi 
a bacKout was performed. 


SEND 


0 








10 


Normal. 






12 






10 


The GTMA C/l cannot dynamically 
anocate a session because either: 

• I he number of existing sessions is 
already the maximum allowed, or 

* C/l cannot obtain any tree storage from 
Hibpc >l 2^0 fo the j^jsion uiago 




8 


4 






10 


No ancnor. 




8 


16 






10 


incorrect input anchor. 




8 


20 






10 


invalid Trancode. 




8 


24 


Caller's 
new state 


Caller's 
old state 


10 


Caller cnanged the program srate or Key 
- see reason codes 3 ana 4, Program 
state and key should remain the same ror 
ail API calls. 




8 


32 


Segment 
number 


Maximum 
size 


10 


Segment is too large. 




8 


40 






10 


Buffer!=segments. 














Invalid send buffer length. 




8 


60 






10 


Missing tpipe name. 




8 


64 






10 


invalid tpipe name. 




8 


68 






10 


invalid tpipe name. First four characters 
of name share the same tpipe prefix In 
otma_open or otma_openx. 




8 


72 






10 


invalid error message parameter 
specified. 




12 


8 


Send 
code 


Send 
code 


10 


Send failed. 








return 
code 






The OTMA C/l service call was rejected 
by the BPESVC service. See "BPE 
Codes" in IMS Version 9: Messages and 
Codes, Volume 1 for more information on 
BPESVC return codes. 




16 










Send has been cancelled by IMS. Either 
IMS is down, or OTMA is stopped. 




20 


NAK code 


NAK 
reason 






Either IMS rejected the input message, or 
a backout was performed. 


RECEIVE 
ASYNC 


0 


0 






11 


Normal. 
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Table 27. OTMA C/l Return Codes and Reason Codes by Function (continued) 



Function 


Return 

Code 

(Decima!) 


Reason 1 
(Decimai) 


Reason 2 
(Decimal) 


Reason 3 
(Decimal) 


Reason 4 
(Dec: ma') 


Description 




0 


44 


Maximum 

number of 

muiti- 

segrnents 

specified 

in the 

receive 

segment 

list" 


Actual 
number of 
multi- 
segments 
sent from 
IMS 


11 


i ne first array element of tne receive 
segment list specifies the maximum 
number of muiti-segments tnat can be 
received from IMS, 

If IMS sends more multi-segments tnan 
the number specified in the receive 
segment list, tne last element in the 
ncrv -> segment list vvil nc udo 1 he sizo 
of the rest of the muiti-segments. Ah of 
the r ult jogr onls will t ■> sto od in *he 
receive burfer. 




4 


12 




0 


11 i Unable to obtain a session block. 




4 


80 






11 1 1 ne hvlS 0 f MA function is nor started. 




8 


18 








Incorrect input anchor. 




8 


20 








Invalid Trancode. 




8 


24 


Caller's 
new state 


Caller's 
old state 


11 i Caller changed the program state or key 
i - see reason codes 3 and 4. Program 
i state and key should remain the same for 
i all API calls. 






48 


Length of 
receive 
buffer 
specified. 


receive 
buffer 
needed to 
include all 
the output. 


11 


Tne size of the receive burfer is too short. 
CnecK the receive_Duffer and 
receive length oarameters. and correct 
the application program to use the ouffer 
size returned in reason code 3. 












11 


Invalid send buffer length. 




8 


60 






11 


Missina tpipe name. 




8 


64 






11 


Invalid tpioe name. 




8 


68 






11 i Invalid tpioe name. First four cnaracters 
i of name share the same tpioe prefix m 
i otma_open or otma_openx. 








return 
code 




11 


OFIVAOi se vice Cdii was settee 
Oy the BPE^VC scrv x See B D E 
Codes " in IMS Version 9: Messages and 
Codes, Volume 1 for more information on 
BPESVC return codes. 




16 








Roceve has sec - m -colled cy r/S 
i Either MS is down, or OTivlA is stopped. 


FREE 


0 


o 






14 


Normal. 




4 


0 






14 i Not allocated. 




4 


4 






14 


Quitting. 




8 








14 


Null anchor. 




8 


8 








Obsolete handle. 




8 


16 






14 


Incorrect input anchor. 
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Tabie 27. OTMA C/l Return Codes and Reason Codes by Function (continued) 



Function 


Return 

Code 

(Decimal) 


Resson 1 
(Decimal) 


Reason 2 
{Decima!) 


Reason 3 
(Decimal) 


RoaSQH 4 

(Decimal) 


Description 




8 


24 


Caller's 
new state 


Caller's 
old state 


14 


Caller changed the program state or key 
- see reason codes 3 and 4. Program 
state and key should remain the same ror 
ail API calls. 




12 


12 


BPESVC 
code 




14 


The OTMA C/l service call was rejected 
uy [ne Drbovo service, oee ore 
Codes" In IMS Version 9: Messages and 
Codes, Volume 1 for more information on 
BPESVC return codes. 


CLOSE 


0 


0 


xcf ixcieav 


xcf ixcieav 


15 


Normal completion. For more information, 
see z/OS MVS Programming: Sysplex 
Services Guide. 




8 




0 




15 


Null anchor. 




8 


16 






15 


Incorrect input anchor. 




12 


8 


xcf ixcieav 


xcf ixcieav 
rsrs 


15 


Non-zero return code from IXCLEAV, For 
more information, see OS/390 MVS 

Reference. 




12 


12 






15 


One of the OTMA C/l service routines 
abended. The abend could be caused by 
incorrect input parameters. If not, save 
the dump and contact your IBM Support 
Center for assistance. 



OTMA Error Messages 



DFS3908E ABEND code IN OTMA SVC INIT 

MODULE DFSYSVSO, PSW=psw1psw2 

Explanation: An abend occurred while module 
DFSYSVIO was in control. Module DFSYSVIO is the 
module that initializes the OTMA Callable Services SVC 
service, and is typically run as a stand-alone job prior to 
running applications that use the OTMA Callable 
Services. DFSYSVIO processing is protected by an 
internal ESTAE, which attempts to retry from the abend 
and clean up any global resources (such as common 
storage) that DFSYSVIO obtained. Message DFS3908E 
is issued to alert the operator that an abend occurred. 

In the message text: 

code The abend code. For system abends, the 

format of code is Sxxx, where xxx is the 3-diglt 
abend code in hexadecimal. For user abends, 
the format of code is lidddd, where dddd is the 
4-digit abend code in decimal. 

pswl The first word of the PSW at abend, 

psw2 The second word of the PSW at abend. 

System action: The DFSYSVIO ESTAE collects 
diagnostic data about the abend, and then resumes 



execution in a cleanup routine within DFSYSVIO. This 
routine attempts to release any global resources that 
DFSYSVIO obtained as a part of Its processing. 
DFSYSVIO then Issues message DFS3911E and returns 
to its caller. Typically, unless the abend occurred at the 
very end of DFSYSVIO processing, the OTMA SVC 
routine Is not Initialized. 

The first time that DFSYSVIO abends, Its ESTAE takes 
an SDUMP of the address space, and causes a record 
to be written to the SYS1 .LOGREC data set to 
document the abend. If DFSYSVIO abends a second 
time or more (within one execution), its ESTAE does not 
take another SDUMP. However, it does write another 
record to SYS1 .LOGREC. 

System programmer response: Save any dump, 
SYSLOG, and SYS1, LOGREC information and contact 
the IBM Support Center. 

Module: DFSYSVIO 



DFS391 1 E ERROR INSTiALiZING OTMA SVC - 
details 

Explanation: An error occurred in module DFSYSVIO. 
Module DFSYSVIO is the module that initializes the 
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OTMA Callable Services SVC service, and is typically 
run as a stand-alone job prior to running applications 
that use the OTMA Callable Services. When DFSYSViO 
cannot complete the OTMA callable services 
initialization, It issues message DFS3911E to indicate 
why initialization failed. 

In the message text: 

details A short summary of the reason why the OTMA 
Callable Services SVC initialization failed. 
details corresponds with the return code issued 
by the DFSYSVIO module, and may be one of 
the following: 

NOT EXECUTING IN PSW KEY 7 

DFSYSVIO was not given control In PSW key 
7. DFSYSViO must run as an authorized 
program in PSW key 7, This is accomplished 
by adding DFSYSVIO to the program properties 
table. Refer to the IMS Version 9 Open 
Transaction Manager Access Guide and 
Reference for instructions on how to add 
DFSYSVIO to the program properties table. 

ESTAE CREATE FASLED, RC= rc 

DFSYSVIO attempted to establish a z/OS 
recovery routine (ESTAE), but the create 
ESTAE call failed, rc is the return code from 
the z/OS ESTAE macro. 

BPESVC SNIT FASLED, RC^rc 

DFSYSVIO could not initialize the BPE SVC 
service, rc is the return code from the BPESVC 
initialization call. 

BLDL FOR DFSYSVCO FASLED, RC= rc 

A z/OS BLDL call for module DFSYSVCO 
failed. Ensure that DFSYSVCO is included In 
the library from which you are running 
DFSYSVIO. rc Is the return code from the z/OS 
BLDL macro call. 



GET FOR STORAGE FASLED, RC= rc 

DFSYSVIO could not get storage required for 
the OTMA Callable Services SVC module, rc is 
the return code from the z/OS STORAGE 
macro call. 

LOAD FOR DFSYSVCO FAILED, RC=rc 

A z/OS LOAD call for module DFSYSVCO 
failed, rc is the return code from the z/OS 
LOAD macro call, 

BPESVC REGISTRATION FASLED, RC= rc 

Registration of the OTMA Callable Services 
SVC routine with BPESVC (BPE SVC services) 
failed, rc is the return code from the BPESVC 
REGISTER macro call. 

ABEND OCCURRED DURING 
INSTSALiZATiON 

An abend occurred during DFSYSVIO 
processing. This message should be preceded 
by a DFS3908E message indicating the abend 
code and PSW, and by an SDUMP of the 
DFSYSVIO job's address space. 

System action: Module DFSYSVIO terminates. The 
OTMA Callable Services SVC is not initialized (or, if it 
was previously initialized, Is not replaced). 

System programmer response: For environmental 
errors (such as DFSYSVCO not being In the same 
library as the one from which you are running 
DFSYSVIO), correct the error and re-run DFSYSVIO. For 
NOT EXECUTING IN PSW KEY 7 error, ensure that the 
library where DFSYSVCO resides is APF authorized. For 
other problems contact the IBM Support Center. 

Module: DFSYSVIO 



GTIrVlA C/l Sample Programs 

The two sample C programs that are shown in this section are for display purposes 
only. The code for the two sample programs is available to licensed customers of 
IMS Version 6 and above in PTF number UQ23685. 

The following topics provide additional information: 

• "Warranty and Distribution for OTMA C/l Sample Programs" 

• "OTMA C/i Sample Program #1: Synchronous Processing" on page 129 

• "OTMA C/l Sample Program #2: Asynchronous Processing" on page 140 

Warranty and Distribution for OTMA C/I Sample Programs 

The code is provided "AS IS." IBM makes no warranties, express or implied, 
including but not limited to the implied warranties of merchantability and fitness for a 
particular purpose, regarding the function or performance of this code. IBM shall not 
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be liable for any damages arising out of your use of the sample code, even if they 
have been advised of the possibility of such damages. 

The sample code can be freely distributed, copied, altered, and incorporated into 
other software, provided that it bears the following Copyright notices and 
DISCLAIMER OF WARRANTIES intact, 
(c) Copyright IBM Corp. 
2006 All Ricihts Reserved. Licensed Materi 
DISCLAIMER OF WARRANTIES. 

The following "enclosed" code is sample code created by IBM Corporation. 
This sample code is not part of any standard or IBM product and is provided 
to you solely for the purpose of assisting you in the development 
of your applications. 



■ Property of IBM 



OTfVf A C/l Sample Program #1 : Synchronous Processing 

The program shown below illustrates how OTMA C/l can be used for synchronous 
(one in-one out) processing. In this sample program, the otma_send_receive API is 



used to send and receive IMS data, 
rforagma langlv I (extended) 



< Callable Interface sample 

' Parameters: 

Server Name 
Client Name 
User Name 



»mg synchronous APIs 



mple: //SENDBUFO DD *,DLM=$$ 
SEND OTMA TO SKS1 
$$ 

< Note: C0MPAR1 is the DON AM E of an 
actual output wi cm expected 
the compare string and 'j' 1 

mole: //COMPARQ DD *.DLM-$$ 
SEND OTMA TO SKS1? 



input ti le usee 
:sutput. ' ?' is 
; used to igno» 



This test program is callable from JCL 
< //NA10TMA JOB CLASS=A.MSGLEVEL= (1.1) „MSGCLASS=H„REGI0N=2M 

* //* iterations command qroupTd 0 [MA Data" 
' //MINISAMP EXEC PGM-NA10TMA, 

' // PARM- ' [ RAP (OFF !/lMS6iCPi 1MS1 ESR 1 /DISP groupid 

OTMAData ' 

/* //STEPLIB DD DISP=SHR,DSN-OTMA. TEST. LOAD 
/* //SYSUDUMP DD SYS0UT=* 
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/* //STDOUT DD SYS0UT=* */ 

/* //STDERR DD SYSQUT-* */ 

/* //CEEDUMP DD SYS0UT-* */ 

./* .//C0MPAR1 DD *,DLM=$$ */ 

/* EXPECTED OUTPUT GOES HERE */ 

/* $$ */ 

/* //SENDBUF0 DD *,DLM-$$ */ 

/* SEND DATA GOES HERE */ 
/* $$ 

/* */ 

/* Note: TRAP (OFF)/ Passes LE run-time option TRAP (OFF) which turns */ 

/* off LE condition handling. To get a LE dump on abend set */ 

/* TRAP ON and provide a CEEDUMP DDNAME, */ 

/* Note: COMPAR1 is the DDNAME of an input file used to compare */ 
/* actual output with expected output. '?' is used to delimit */ 

/* the compare string and ' | ' is used to ignore a char compare*/ 



/* An example for using the OTMA Client API in C iang. */ 

/* This program is broken into the following parts: */ 

./* Declarations for special support */ 

/* Process invocation parameters */ 

/* Setup for C signal handling */ 

/* Do XCF open processing and analysis */ 

/* Do session allocate processing */ 

/* Execute a command or transaction per invocation parm */ 

/* Do session free processing */ 

/* Do close */ 

/* End */ 



/* API's for non-authorized OTMA caller */ 

#include "dfsycO.h" /* Non-authorized GTMA API's */ 

#include <stdlib.h> /* Standard C Header file */ 

#incl ude <stddef.h> /* Standard C Header file */ 

^include <stdio.h> /* Standard C Header file */ 



/* internal functions */ 
int memc(char *comp_buf, char +rec_bufl ); 

/* macro to move string to blank filled left justified char field */ 
#define splat(t.s) \ 



memset((char*)&(t) , ' ' ,sizeof (t!) ;\ 
strncpy ( (char*) &(t) , s ,strlen(s));} 

/* standard math routines 

fdefine min(a,b) ( (a)<(b) ? (a) : (b) ) 

^define max(a,b) ( (a)>(b) ? (a) : (b) ) 

main(int argc.char *argv[]) 



/* Following fields used by all Functions */ 

/* Handle returned by create */ 

/* and used by all others. */ 

/* Return code returned by all . */ 

/* Return code save area */ 
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sess_ 


_handl e_t 


sessjiandle; 


/* Handle returned bv allocate * 








/* used bv send__recenve and free. * 


OtTO 


_qrp_name_ 


t grp name; 


/* API XCF Group Member Name. * 


01 Hd" 




"t c It . name; 


h APi XCr CI ler-t M^rt^t N<j«v 


otma_ 




_t srv_name; 


h A>n *CF Server Mt^i 'vt^. 








/* (IMS's XCF member name). * 




uid_t 




/* Our z/GS logon ID. * 




_prt_t 


groupid; 


/* RACF Group ID * 


01 Hd" 






/* Otma Data * 


Iter- 


UiameJ: 




/* Lterm name * 



signed char ern 
' i yn> 5 d har ■ 



I* ModName 

aqe_text[120];/* IMS error msg field 

/* A place to receive any 1Mb 

/* DFS error messaaes. 
saqe = (unsigned char*)&error_messaqe_text; 

/* a pointer to which is parameter 

/* on se 



We fin. 
#defint 
#defin< 



ame_t tranjiame; 

BUFFER LEN 4096 

N1JM_BUFFER 60 

C0M_BUFFER 86 

GROUP NAME "HARRY" 



' Tiansartion 
* <»t ou<- buffet 



Set XCF group n 
Compare buffer 



impare buf [NUM BUFFER + 1] ; 
lq bufferjength = 0; 

ia rec_buf f erj en = BUFFER_LEN; 

rec.buf [BUFFER. LEN I; 
it rec_data_l en = 0; 

send_buf i BUFFER_LEN| ; 

tempJ)uf[NUM_BUFFER] ; 

_! context - {0 v 00u00u00u00u00u00u00u00u00000000 ; 

/* This test is not distributed sync point. 

/* loo complicated tor here. 

/* Normally this is obtained from RRS 



/* The callable interface makes use or z/OS tvent Control Blocks. 
/* Any language which call tne interface must deal with this. 



unsigned long *(ecb_l ist[2]) ; /* z/OS pause stuff 

unsigned long **pecb_hst: 

ecbj: ecbOPEN = 01.; /* ecb to be posted bv OTMA API 

ecb_t ecblO -■ OL; /* ecb to be posted by OTMA API 

ecb_t signal = UL; /* ecb to be posted by C runtime 

ecb_t temp__ecb = OL; /+ used by compare and swap 

ecb_t reset_ec» « OL; /* used bv compare and swap 



Local variable 1 
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signed long sessions; /'* number of sessions to support */ 

tpipe_prfx_t tpipe_prefix; /* first part of tpipe NAME */ 

FILE * stream; 

int num: /* number of characters read from stream */ 



/* To support test functions - names of 
/* Print the parms out tor documentatic 



char * argdets|8]= 



cl lent name 1 
iterations ' 



/* 1 
/* 2 



Declare an arr^v of compare file ddnames to 
compare actual output received with expected outout. 



char * infiledd[4H"DD:COMPAR0". /* 1 

"DD:C0MPAR1" , /* 2 

"DD:C0MPAR2" , /* 3 

"DD:C0MPAR3" , /* 4 



/* Declare an array of send file ddr 
/* send application data to GTMA. 



- sndfi ^dd['li~ "Q[i 



SENDBUFQ" . 
SENDBUF1" 
lENDBDFJ ' 
SiKDRDFT 



/* Anounce the startup of the test program. */ 

/* */ 

printf ("OtmciOl Starting, version %s %s\n" ,_DATE__,__TIME_ ); 

/* */ 

/* z/OS Pause Init - do this first, in case it fails bail out, */ 
/* This sets up a C environment for signaling from the API. */ 



ecbjist[0] « (unsigned long *) &(signal); /* post by C signal */ 

ecbj i st [1] - (unsigned long +) /* post by OTMA */ 

((unsigned long)&(ecbQPEN) j 

(unsigned long) 0x80060060) ;/* end of list */ 

pecb list = &ecb list[0]; /* pointer to list */ 

/* define callable I/F */ 

/* Begin Test Case... */ 
/* Anounce the startup of the test program. */ 

printf ("0TMCI01 Run Date: %s Run Time; %s\n" , DAT E , T I M E ); 
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/* Process parms/comrnand 1 ine arguments. ^ 



/* First, print the parameters. */ 
print f ("Invocation parameters = \n"); 
for (1=1 ; i<(min(8,argc));i++) 

printf ("%d %s - ", i , argdef s[i] ) ; 
printf ("%s.\n", argv[i]) ; 





(argc>l) 


splat( srv name, 


argv[I]) 


/* XCF memname of IMS » 


el 




splatf srv_name, 


"IMS61CR1"); 


/* hard coded default 




S (argc>2) 


splat( clt name, 


argv[2]J 


/* CI i ent name 


el 




spiat( clt.name. 


"XCFTEST" ) 


/* hard coded default - 1 




(argc>3) 


splat( userid , 


argv[3]) 


/* ID to use 


el 




splat( user id , 


"XCFTEST" ) 


/* hard coded default > 


f 


(argc>4) 


iterations = a to 


(argv[4]) ; 


/* loop count 


el 




iterations = 1; 




/* hard coded default 


f 


(argc>5) 


tran = argv[5]; 




/* Transaction/IMS CMI> 


e! 








/* hard coded default * 






splat( groupid, 


jrgv[6]) 


/* Group ID to use > 


el 




splat( groupid, 




/* hard coded default 




S (argc>7) 


splat( otma_data 


, argv[7]) 


/* OTMA Data 


el 




splat( otma_data 




/* hard coded default * 



/* Open the file with the ddname SENDBUFO supplied in the */ 
/* JCL which invoked this C driver. Then read the file into */ 
/* temp__buf. */ 



if ({ stream = fopen("DD:SEND8UF0","rb")} !- NULL ) 
{ 

num - fread( temp_buf, sizeof( char ), NUM_BUFFER, stream ); 
printf ("BUFF SIZE = %d.\n\ num) ; 
if (num — NUM_BUFFER) \ 
printf { "Number of characters read = %i\n", num }; 
fclosef stream ); 

else { 

if ( terror (stream) ) 

printf ( "Error reading DDNAME sendbufO/n") ; 

else if ( feof (stream)) { 

printf ( " EOF found\n" ); 

printf ( "Number of characters read %d\n", num ) ; 

printf ( "temp_buf - %.*s\n", num, temp_buf) ; 

fclosef stream ) ; 



} 

else 

printf ( "ERROR opening DDNAME sendburu/n" ); 

/* Initialize API parameters and buffers. 

splat( grp_name,GRQUP_NAME ); /* XCF Group Name 

splat( tpipe_prefix,"TPAS" ); /* Tpipe Prefix Narr 

splat( tran. name, tran ); /* do scan here 

strncat(send_but, tempjbuf ,num); /* Copy temp_bur into send J 

butfer_length = strl en I send_buf) ; /+ Set send buffer length 



/* Example or setting up parms to Open the aCF Link 



retrsn.ret = -1; 
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retrsn.rsn[0; 
retrsn.rsnjT 
retrsn.rsn[2; 
retrsn.rsnK 



= -1; 
, „ 1; 



/* OTMA supports multiple parallel 

/* sessions (TPIPES) How many do you want? 



/*BEGIN: 

/* vie have a CREATE function to set tip storage and 

/* an OPEN function to start the protocol. 

/* If you don't need to customize the environment you can st 

/* with the OPEN function, the CREATE will be done by OPEN. 



/* (out) ptr to addr to receive ancr 
&retrsn, /* (out) return code 

(ecb_t *) &ecbOPEN,/* not posted by create but stored 



&grp_r 
&srv r 



/* (in) ptr to valid groupname */ 

/* (in) Our member name */ 

/* (in) Our server name */ 

/* (in) number of sessions to support*/ 

/* (in) first part of tpipe name */ 



p r i n t f ( " OTM A_C R EAT E issued, ret - %d r 



rsn[0], 
rsn[l], 
rsn[2], 

rsn [3], 



printf("-\n"); 
/* Connect to IMS 



otma_open(&anchor, /* out ptr to addr to receive anchor */ 

&ret;rsn, /* out return code */ 

(ecb_t *)&ecbOPEN, /* out posted by open if failure */ 

/* el se posted by exit pgm */ 

&grp_name, /* in ptr to valid XCF groupname */ 




*/ 



&sessions, /* in number of sessions to support */ 

&tpipe_prefix /* in first part of tpipe name */ 
); 

printf ("0TMA_QPEN issued, ret - %.8x rsn - %,8x,%.8x,%.8x,%.8x\n" 
" Waiting for ecb at %.8x.=%.8x.\n", 
ret rsn. ret, 
retrsn.rsn[l], 
retrsn.rsn[2] , 
retrsn.rsn[3] , 
ecb list[l], 
*ecb_l istri] 
); 
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printf ("-\n"}; 

/* */ 

/* Hen; we; wait for Open to signal complete */ 



DFSYCWAT(ecb_list[l]); /* WAIT on ecb *; 

printf ( "0PEN_0TMA done, ret - %.8x rsn - %.8x,%.8x,%.8x,%.8x \n" 
"\nEcb at %.8x.- %.8x.\n", 

retrsn.rsn[G] , 
retrsn.rsn[l] , 
retrsn.rsn[2] , 
retrsn.rsnD] , 
ecbJistlT], *ecbjistm 
); 

printf ("Local Area Anchor at %8.8X - %8.8X\n", 
Sanchor, anchor); 

printf ("An"}; 

/* */ 

/* The post code from open indicates success or failure */ 



if (0!=(0x00ffffff & ecbOPEN)) 

printf ("0PEN_0TMA ecb is posted fail ure.\n") ; 
return (retrsn . rsn [6] ) ; 



/* Set userid to blanks if userid = bobdavis */ 

printf(" Trans - %.8s,\n ", tran_name !; 

printf (" Userid = %.8s,\n ", userid ); 

printf ("Grouped = ?.6s,\n ", qroupid ); 



' Like CREATE the ALLOC function lust creates control blocks */ 

< and stores data in tnem. Other functions may be invented */ 

< to modify these structures before the command-of-execution,*/ 

< SEND_RECEIVE is issued. */ 



&anchor, 


/* in ptr to global word */ 


&retrsn, 


/* out rc,reason(l-4) */ 


&sess handle, 


/* out session id */ 


NULL, 


/* in default overrides */ 


&tran_name, 


/* in IMS tp name or cmd */' 


Suserid, 


/* in RACFid or blanks */ 


&groupid 


/+ in RACF group id or blnk*/ 



3TMA ALLOC done 





-i.ret, 




T.rsn[G], 




i.rsn[l]. 


retrs 


T.rsn[2] s 


retrs 


!.rsn[3] 



*.8x,%.8x,%.8x,%.8x\n' 
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/* Even if ALLOC fails we go < 
/* API will reject the call. 



**************************************************/ 

; call that sends the data and prepares to */ 
s answer from IMS, */ 



with multi pi < 



__Send message wait for reply__ 



for (loop_count = 6 ; loop_count<iterations ; 1 oop_count++) 

/* Change the environment to wait for ecblO */ 

ecblO = 0; /* clear ecb for reuse */ 

ecb_list[l] = (unsigned long *) /* posted by OTMA */ 

((unsigned long)&(ecbI0) j 

(unsigned 1 ong) 0x80000000) ; /* end of list */ 

if (loop count != 0) 

{ 



/* If looping more than once open the next file to senc 
/* and read it into the send_buf. 



if (( stream = fopen(sndfiledd[Ioop count] , "rb") ) != NULL ) 

{ 

num = fread( temp bur, sizeof( char ), NUM BUFFER, stream ) 
printf("BUFF SIZE - %d.\n", num); 
if (num — NUM_BUFFER) { 
fclose( stream ) ; 

} 

else { 
i f ( terror (stream) ) 

printf( "Error opening file %s\n" ,sndf i 1 edd [1 oop__count] } 
else if ( feof (stream)) { 
printf( "EOF foundW ); 

printf ( "Number of characters read %d\n", num ); 
printf ( "temp_buf - %.*s\n", num, temp_buf ) ; 

fclose( stream ) ; 



printf ( "Error opening file %s\n", sndfiledd[loop_count]) ; 
/* Initialize send and receiving buffers. */ 
memset (rec_buf ,0, sizeof (rec_buf)) ; 
memset (send_buf ,S, sizeof (send_buf) ) ; 
strcat(send_buf, temp_buf ); 
strcat(send_buf, " " ); 
bufferjength = strlen(send__buf); 
printf ("%s\n" ,send_buf) ; 

printf ("buffer length = %d\n", buffer_l ength) ; 
} /* end if loop_c:ount !- 0 */ 

/* Print otma_send_receive parms and start of API */ 

memset (error_message_text ,0, sizeof (error_message_text)) ; 

printf ("Send buf at %.8x.\n", &send_buf ) ; 

printf ("Send buf = %s.\n", send__buf ) ; 

printf ("Receive buf at %.8x.\n\ &rec_buf) ; 

print f("Lterm = %.8s.\n", Iterm ); 

printf ("Modname = %.8s.\n" s modname ); 

printf ("-\n"); 
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&anchor, 
&retrsn, 
&ecbI0, 

&sess_handle, 
&1 term, 
&modname, 

(unsigned char *) &send_buf, 

&buffer length, 
0, 

(unsigned char *) &rec:_buf, 

&rec_buffer_ien, 
&rec data len, 
0, 

Scontext, 
&error_message, 
&otma_data) ; 

printf ("0TMA_SEND done, ret - %.8x 
retrsn.ret, 
retrsn,rsn[Q] , 
retrsn.rsn[l] , 
retrsn.rsn[2], 
retrsn.rsn[3.]) ; 



/* (in) anchor block */ 

/* (out) return status */ 

/* (in) ecb address */ 

/* (in) session handle */ 

/* (in/out) logical terminal */ 

/* (in/out) module name */ 

/* (in) send buffer */ 

/* (in) size of send buffer */ 

/* (in) send_segment_iist */ 

/* (in) receive buffer 

/* (in) size of buffer */ 

/* (out) received data length */ 

/* (in/out) receive seg list */ 

/* (in) context id */ 

/* (out) ims message */ 

/* (in) Otrna Data */ 

rsn - %.8x,%.8x,%.8x,%.8x\n". 



/* Here we wait for receive to signal complete 

/* An application can go do other thing while IMS is processing and 
/+ while the XCF scheduled SRBs are returning data to the caller's 
/* buffers. DO MOT DEALLOCATE THE BUFERS WHILE THIS IS GOING ON I 
/* None of the output areas of the SEND_RECIEVE can be freed until 
/* the ECB is posted complete. 



st[l]); /* WAIT on ecb 

>n.ret; /+ Save Receive 



) r i n t f ( " OTM A_R EC E I V E done. 

"\nEcb at %.8x.= %. 
retrsn.ret, 

ret rsn ^ rsn [1L 
retrsn.rsn [2] , 
retrsn.rsn [3] , 
ecb_list[l], 
*ecb_list[l] 



/* Error path Free allocated session *./ 

printf ("-error path ret rsn. ret =%d\n" .retrsn.ret); 
P rintf ("-\n"); 

printf ( "Error message - %s\n", error_message ) ; 

otma_free( 

& anchor, /* (out) ptr to global word */ 

& retrsn, /* (out) rc, reason (1-4) */ 

& sess_handle /* (in) unique path id */ 



printf ("GTMA_ FREE done, ret = %.8x rsn - %.8x,%.8x,%.8x,%.8x \n", 
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i.- n | 0 1 , 
i-rs,n|ll, 
i.rsn[2], 



/* Sever IMS connect! 01 

printf("-\n»); 
otma_c1ose( 

& anchor, 
8 retrsn 



' (in, out) tr to otma anchor */ 
■ (out) re, reason (1-4) */ 



printf("OTMA_CLOSE done, 
retrsn. ret, 
retrsn. rsn [0] , 
retrsn . rsn | "11 , 
retrsn. rsn [2], 
retrsn. rsn [3] 



If SEND RECEIVE worked . 



;ceive API return c 



Open the compare file c* 
of the receive buffer, 
with the actual output < 



itainina the expected output; 
Compare tne expected output 
id return the result. 



rec_buf[8] - ' /* Remove possible NL ie x'15' */ 

prmtt( "intiledd = %s\n". i nti 1 edd I 1 oop__count | ); 

it ({ stream fopen(mf i ledd| loop_count] , "rb")) != NUlL ) 

num - fread( compare_buf, sizeoff char ), COM_BUFFER, str. 
if (num COM_BUFFER) { /* fread success */ 
printf( "compare_but = 'Ss\n", compare_buf ); 
printf( " rec_buf --■ %s\n", rec__buf ); 

comparejresult - memc( comparejbuf, rec_buf h 
printf( "compare_result = %i \n" .coinpare_resul t) ; 
it (compare result != u) 
return (conipare_resultj; /* Exit if NO COMPARE 



>o fuadO la^d i 

if ( terror (stream) ) 

prmtt{ "Error readino 
•Isc i t ( iooi (s1 ream) ) { / ^ pos 

pnntfl "EOF round \n" !; 

prmtr( "Number or characters read 

prmtt( "compare_buf = %.*s\n", nut 



/* possibility 1 * 
S\n' , mi i iedd[lo 
h possibi I ■ t v ? n 



else 

printf( "Error opening file : 
} /'* end of loop */ 



i nf i 1 edd [1 oop_count] ) ; 



/* Once a message is sent to IMS and the 
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/* is usual to release the tpipe for use by other transactions. */ 

/* For conversational trans an application would keep using */ 

/* the handle to continue a conversational transaction with IMS, +/ 

/* The Transaction name is specified in the ALLOC and it is */ 

/* intended that a FREE, be done at the end of each transaction */ 

/* and a new ALLOC be done for the next one. This is not */ 

/* expensive. */ 

printf ("-\n") ; 
otma_free( 



out) ptr to global word 
out) rc, reason (1-4) 
in) unique path id 



'0TMA_FREE done. 



rsn[0] , 
rsn[l], 
rsn[2], 

rsn[3] 



printf ("-\n"); 



/* Finally, CLOSE severs the connects 
■< Storage used by the OTMA API. 



with IMS and frees the 



* This will 

* 


be done at job- step termina 


ion but its untidy. 


otma_d ose( 








& anchor, /* (in 


out) ptr to otma anchor 




& retrsn /* (ou 


) rc, reason (1-4) 


); 

printfC'OTMA 


.CLOSE done, ret = %.8x rsn 


%,8x,%.8x,%.8x,%.8x \n 


retr" 






retr 


n.rsn[0] , 






n.rsn[l], 






n.rsn[2j. 






n.rsn[3] 





return (compare_resul t) ; 
] /* end of main */ 



/* Retern return code 



/* Suoroutme to compare expected resu i ts (compare_buf ) */ 

/* with actual resul is (errjiisg) the " I !l is used to sigmty */ 

/* an itsnore compare and "?' ! is used to mark the end of string. */ 

/* Note: Compare starts using an index ■=! le. the 2nd character */ 

/* because the 1st character was blanked out, ( NL x' 15 ' ) */ 



; (j-6) && (comp_buf[i] 
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if( comp_buf [i] !--■ '|' ) /* Ignore compare 

if( comp_buf[i] != rec_bufl[i]) /* compare ok ? 



printf( "MISCOMPARE !!! \n" ); 

printf( "comp_buf [%d] = %c\n", i, comp_buf[T| ); 

printf( "rec_bufl[%d] = %c\n" s i, rec_bufl[i] ); 



*/ 



OTMA C/i Sample Program #2: Asynchronous Processing 

The following program illustrates how OTMA C/l can be used for asynchronous 
(unsolicited) processing. In this sample program, one otma_send_asynch and one 
otma_receive_asynch call are performed in a loop. 

Recommendation: If you will be using synchronous (one in-one out) processing 

exclusively, use the otma__send_receive API. The otma_send_receive API provides 
the most efficient means of synchronous processing. 
#pragma langlvl (extended) 

/* *'/ 

/* Callable Interface sample program using asynchronous APIs */ 

*/ 

/* Parameters: */ 

/* Server Name */ 

/* Transaction */ 

/* User Name */ 

/* User Group */ 

/* Lterm */ 

./* Mod Name */ 

/* OTMA Data */ 

/* Iterations */ 

/* Note: The send buffer is sent as a file with a ddname of */ 

/* SENDBUFn in the invoking JCL. */ 

/* */ 

/* Example: //SENDBUFO DD *,DLM=$$ */ 

/* SEND OTMA TO SKS1 */ 
/* $$ 

/* Note: C0MPAR1 is the DDNAME of an input file used to compare */ 

/* actual output with expected output. '?' is used to delimit */ 

/* the compare string and ' | ' is used to ignore a char compare */ 

./* Example: //COMPARED DD *,DLM=$$ */ 

/* SEND OTMA TO SKS1? */ 

/* $$ */ 

/* Note: TPIPBUFn is the DDNAME of an input file used to specify */ 

/* the tpipe name to be used for each iteration. */ 

/* */ 

/* Example: //TPIPEBUFO DD *,DLM=$$ */ 
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/* Entry... */ 

/* */ 

/* This test program is callable from JCL */ 

/* //NA10TMA JOB CLASS=A,MSGLEVEL=(1 ,1) ,MSGCLASS=H,REGI0N=2M */ 

/* //+ PARM^serverjnemberjname cl ient_rcember_name transaction */ 

/* //* user_name groupjiame ltermjiame ModName 0TMA_Data */ 

/* //* iterations */ 

/* //MINISAMP EXEC PGM-NA10TMA, */ 



/* // PARM='TRAP(0FF)/IMS61CR1 IMSTESR G2I4992 /DISP userGI groupid */ 

/* // Lterm ModName OTMAData 1 1 */ 

/* //STEPLIB DD D I S P=S HR , DSN =0TMA .TEST. LOAD */ 

/* //SYSUDUMP DD SYS0U1"=* */ 

/* //STDOUT DD SYS01JT=* *./ 



/* //STDERR DD SYSOUT-* */ 

/* //CEEDUMP DD SVSOUI ■■■ */ 

/* //COMPAR1 DD *,DLM-$$ */ 

/* EXPECTED OUTPUT GOES HERE */ 

/* $$ */ 

/* //SENDBUFO DD +,DLM=$$ */ 

/* SEND DATA GOES HERE */ 

/* $$ */ 

/* //TP1PBUF0 DD *,DLM=$$ */ 

/* TPIPE NAME GOES HERE */ 

/* $$ */ 

/* */ 

/* Note: TRAP (OFF)/ Passes LE run-time option TRAP (OFF) which turns */ 

/* off LE condition handling. To get a LE dump on abend set */ 

/* TRAP ON and provide a CEEDUMP DDNAME. */ 

/* */ 

/* Note: COMPAR1 is the DDNAME of an input file used to compare */ 
/* actual output with expected output . '?' is used to delimit */ 

/* the compare string and is used to ignore a char compare*/ 



/* An exampl e for using the OTMA Client API in C lang. */ 

/* This program is broken into the following parts: */ 

/* Declarations for special support */ 

/* Process invocation parameters */ 

/* Setup for C signal handling */ 

/* Do XCF open processing and analysis */ 

/* Execute an API to send data per invocation parm */ 

/* Execute an API to receive data per invocation parm */ 

/* Do close 

/* End */ 



/* Header Definitions. 

^include "dfsycO.h" /* Non-authorized OTMA API's 

#include <stdlib.h> /* Standard C Header file 

#i ncl ude <stddef.h> /* Standard C Header file 

#include <stdio.h> /* Standard C Header file 



/* Internal functions 
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/*********************************************************************/ 

/* memory comparison macro. */ 
/* int mesne (char *comp_buf, char *rec_bufl ); */ 

/* */ 

/* macro to move string to blank filled left justified char field */ 
/* #define splat(t,s) \ */ 

/* memset{(char*)&{t}, ! 1 .sizeof (t)) ;\ *'/ 

/* strncpv((char+)&(t) , s .strlen(s) ! ; \ */ 

/* ' ' */ 

/* standard math routines */ 
/* #define min(a.b) ((a)<(b)?(a):(b)) 

/* fdefine max(a,b) ( (a)>(b) ? (a) : (b) ) */ 
/*********************************************************************/ 

/* This OTMA C/l Program */ 

/* Note: TRAP (OFF)/ Passes LE run-time option TRAP (OFF) which turns */ 
/* off LE condition handling. To get a LE dump on abend set */ 

/* TRAP ON and provide a CEEDUMP DDNAME. */ 

./* Note: C0MPAR1 is the DDNAME of an input file used to compare */ 
/* actual output with expected output. '?' is used to delimit */ 

/* the compare string and 'j' is used to ignore a char compare */ 

*/ 



main (int argc.char *argv[]) 

/,., Kilil Kilil K „ K „ K „ K „ ^, ^, ^ ^ ^ ^ **. A **. A *,. A ,.,. A ,.,. A w 

/* Fields used by OTMA C/l APIs. */ 



/* The following fields used by all the OTMA C/l API's. */ 

/* and "used by ail others. */ 

otma_retrsn_t retrsn; /* Return code returned by all, */ 

*/ 

/* The following fields are used by the otma_create and */ 

/* otma_open API's. */ 

otma_grp_name_t grp_name: /* API XCF Group Member Name. */ 

otma_clt_name_t clt_name; /* API XCF Client Member Name. */ 

otm3_srv_name_t srvjriame; /* API XCF Server Member Name. */ 

/* ( IMS' s XCF member name). */ 

signed long sessions; /* number of sessions to support */ 

tpipe_prfx_t tpipe_prefix; /* first part of tpipe NAME */ 

/* The following fields are used by otma_send_async API. */ 

tpipe_name_t tpipe; /* User Tpipe Name. */ 

tran name t trans; /* IMS Trancode or CMD. */ 

racf_uid_t userjiame; /* RACF UserlD. */ 

racf_prf_t user_prf; /* RACF Groupname. */ 

I t;erm_name__t 'I term; ./* Input Lterm, */ 

mod_name_t modname; /* Input Modname. */ 

otma user t otma data; /* OTMA Userdata. */ 

char sendjbuf [BUFFF.RJ.EN] ; 

int long buffer_iength = 0; /* Send Buffer length. */ 

unsigned char error. messagejext [120] ; /* IMS error msg field - */ 

/* A place to receive any IMS */ 

/* DFS error messages. */ 
unsigned char *error_mess3ge » (unsigned char*)&error_message_text; 

/* a pointer to which is parameter */ 

/* on send_receive. */ 
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otma_prof ile2_t send_options; /* Send Special Optic 
/* Ine toll owing fielas are used by otina_recei ve_as\ 



1 term_ 



Jter- 



/* Output Lterm, 
mod. name .t recjnodname; /* Output Mocmame. 

otma_user_t rec_otma_data; /* OTMA Userdata, 

char rec_buf ! BUFFER_LEN I ; 

int long rec_hufferjen = BUFFER LEN; 

long int rec_data_len 
otma profile3 t rec optic 



/* Receive Spe 



/*** 



The callable interface makes 
Any language which call the i 



isianed long *(ecbj 
Tsigned long **pecb_l 



st |2]); /* z/OS pause ecb list 



OL 



-cb to be posted by OTMA API 
»cb to be posts d b>' OTMA API 
* ecb to be posted by C runtime 



1 ) ; /* post by C signal 
* post by Or MA 



ist|OI (unsigned long *) &( 
ist [II = (unsigned long *) 

((unsioned lonq)&(ecbOPEN) I 

(unsigned lonq) 0x80000000); /* end of list 
list = &ecb list[0]; 



/* pointer to list 
/* define callable I/F 



oop_count: 
( o-pai e__i e' 



/* Return code save at 
* Number of iterations t;< 
t Number of iterations u< 
'* Return Code result of 
'* comparison for buffer: 



/* Local Constants 



4096 



; BUFFER_LEN 
; NUMJ3UFFER 80 
; GROUPJiAME "HARRY" 
^•p buf[IvJM BUFFER] ; 



/+ Set our buffer sizes 
/x Sot th>> nu-I">) bul fcrs 
/* Set XLF aroup name to join 
< Swapping buffer 



:ompare_buflNUM_BUFFER + 1]; /* Compare buffer 



srgdets[10] =f "Program Name 
"Server Name 
"Client Name 
"lransaction 
"User Name 
"User broup 
"Lterm 



or parms in order to pring 
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/* Declare an array of compare file ddnames to 

/* compare actual output received with expected output. 



char * infiledd[4]=f"DD:C0MPAR0", 

"DD:C0MPAR1" , 
"DD:C0MPAR2" , 
"DD:C0MPAR3" 



/* Declare an array of send file ddnames, to 
/* send application data to OTMA, 



char * sndfiledd[4V- 



SENDBUFO", 
SENDBUF1" , 
SENDBUF2" , 
DD:SENDBUF3' 



: tpipe names ddnames for the 



i icddi'lj {"DD:TPIPBUFO", /* 1 

"DD:TPIPBUF1" , /+ 2 

"DD:TPIPBUF2" , /* 3 

"DD:TPIPBUF3" , /* 4 



/* Begin Vest Case. . . 

/* Anounce the startup of the test program. 



intf("0TMCIQ2 Run Date: %s Run Time: %s\n" , DAT E , T I M E__ 



■ocess parms/command 1 



/* First, print the parameters. */ 
prmtf ("Invocation parameters --■ \n' 
for (l-l ; 1<(m1n(ll,argc));1«) 

printf(' ! %d %s = ", i, argdefsj 
printf("%s.\n", argv[ij) ; 



if (argol && strcmp(argv[l] ."NONE") != 0) 



splat( srv_.na.me, "IMS61CR1"); /* 
if (argc>2 && strcmp(argv[2] , "NONE") != 0) 
sp1at( clt_name, argv[2]) /* 



/* Server Name. 
Hard coded de 
Client name 
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splat( cltjiame, "XCFTEST" 
if (argc>3 && strcmp(argv[3" 

splat( trans, argv[3]) 
else 

splat( trans, ; 
if (argc>4 && strcmp(argvjX 
sp1at( user. 



-gv[4]j 

'); 



splat( user_ , 

if (argc>5 && strcmp(argv[ 
splat( user_prf, argv[5] 



splat( 
if (argc: 
splat( 



serjprf, '"' ); 

&& strcmp(argv[f 
term , argv[6]) 



splat( Iterm . '"' ); 
if (argc>7 && strcmp(argv[7j , 

splat( mod name , arqv[7]) 
else 

splat} modname , " l! ) ; 
if (argc>8 &&. strcmp(argv[8] ."NONE") 

splat( otma_data, argv[8]) 
el se 

splat{ otma data, "" ) ; 
if (argc>9 &&"strcmp(argv[9] . "NONE") 
^iterations = atoi (argv[9]j; 

iterations = 1; 



/* Hard coded default */ 
= 0) 

/* IMS Tran/Cmd to use*/ 
/'* Hard coded default */ 



t Hard coded default * 



/* Hard coded default * 
1= 0) 

/* Lterm to use * 

/* Hard coded default * 
1= 0) 

/* ModName to use * 



/* OTMAOata to use * 

/'* Hard coded default * 
= 0) 

/* Loop count * 

/* Hard coded default * 



/* 

/* Open the file with the ddname SENDBUFO supplied i 
/* JCL which invoked this C driver. Then read the f 
/* temp_buf. 



= fope 



["DD:SENDBUF0","rb")) != NULL ) 



num --■ freadf temp_buf, sizeoff char ), NUM_BUFFER, stream ); 
if (num — NUM_BUFFER) { 

printf ( "Number of characters read = %i\n", num ); 

fclose( stream ) ; 

01 if ( f error ( stream) ) 

printf ( "Error reading DDNAME sendbufQ/n") ; 

else if ( feof (stream)) { 

printf ( "EOF found\n" ) ; 

printf( "Number of characters read %d\n", num ); 

printf ( "temp_buf = %.*s\n", num, temp_buf) ; 

fclose( stream ); 



printf ( "ERROR opening DDNAME sendbufO/n" ); 



/* Initialize parameters for the otma_create and otma_open */ 



splat( qrp name, GROUP NAME ); 
splat( tpipej)refix,"fPAS" ); 
strcat (send_buf , temp_buf ); 
strcat(send_buf , " " ); 



/* XCF Group Name */ 
/* XCF Group Name */ 
/+ Copy temp_buf into send_buf */ 
/* add a blank for strlen */ 
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bufferjength - strU 



* Example 


of setting up p 


arms to Open the XCF Link 


retrsn.r 


t - -1 








n[0] = -I 








n[l] = -1 








n[2] = -1 








n[3] = -1 

-= 0 








- 10 


/ 


* OTMA supports multiple parallel 






/ 


* sessions (TPIPES) How many do you want? 



/*BEGIN : 

/* We have a CREATE, function to set up storage and 
/* an OPEN function to start the protocol. 

/* If you don't need to customize the environment you can start 
/-■ with the OPEN function, the CREATE will be done by 0PEN - 

otma_create(&anchor, /* (out) ptr to addr to receive anchc 

&retrsn, /* (out) return code 

(ecb_t *) &ecbOPEN,/* not posted by create but stored 



/* (in) ptr to valid groupname 
/* (in) Our member name 
/* (in) Our server name 



&grp_r 
&srv~r 



&sessions, /* (in) number of sessions to support*, 

&tpipe_prefix /* (in) first part of tpipe name *, 



printf ("OTMA_CREATE issued, ret - %d r 
" anchor is at %.8x.\n", 

lltrtl'.rtl'lQ], 
retrsn.rsn[l] s 
retrsn.rsn[2], 
retrsn.rsn[3], 



: %.8x,%.8x,%.8x,%.8x\n' 



printf("-\n"); 



/* Time to try to connect to IMS 



__start XCF connection */ 

i_open (&anchor, /* out ptr to addr to receive a rich 

&retrsn, /+ out return code 

(ecb_t *)&ecbOPEN, /* out posted by open if failure 

/* else posted by exit pgm 

Sgrpjiame, /* in ptr to valid XCF groupname 



/* 



n Our n 



&sessions s / 
&tpipe prefix / 

); 

printf("01"MA_GPEN issued. 



l number of sessions to support 
l first part of tpipe name 



«.8x rsn - %.8x,%.8x,%.8x,%.8x\n" 
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" Wait 


ing for ecb at %.8x.=%.8x 


retrsn 


. ret , 


retrsn 


.rsn[l], 


retrsn 


.rsn[2], 


retrsn 


.rsn[3], 


ecb li 


st[l], 


*ecb 1 


ist[l] 



/+ Here we wait for Open to signal complete 
DFSYCWAT(ecb_list[l]); /* WAIT on ecb 



ecbji; 

); 



■sn [0] , 
-sn[l], 
-sn[2], 



:al Area Anchor at %8.8X - %8.8X\n' 
&anchor, anchor); 



/* The post code from open indicates 
if (Q! = (0x00ffffff & ecbOPEN)) 



printf("OPEN_OTMA ecb is posted faili 
return (retrsn. rsn[0]); 



/* This is the loop that sends and receives data. 
/* 

/* This test program can iterate with multiple calls here. 



= G : loop__count<iterations : 



/* Change the environment 
ecb 10 - 0; 
ecb_list[l] - iu 
((' 



for ecb 10 */ 
/* clear ecb for reuse * 
gned long *) /+ posted by OTMA * 

igned long)&(ecbI0) j 

end of 1 ist * 



msi gned I ong) 0x80000000) ; 
i oop__count ! = 0) 



/* If looping more than once open the next file to send */ 
/* and read it into the send_buf. */ 

if (( stream fopen (sndf i T edd [loop_count] , "rb") ) \ -- NULL ) 

num - freadf temp_buf, sizeof( char ), NUM_B!JFFER, stream ); 
if (num — NUM_BUFFER) { 
fc'iose( stream ) ; 
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} 

else { 
if ( f error (stream) ) 
printf ( "Error open ing file %s\n" ,sndf i 1 edd [1 oop_count] ) ; 
else if ( feof {stream}} { 
printf ( "EOF found\n" }; 

printf ( "Number of characters read %d\n", num ); 
orintf( "temp_buf = %.*s\n". temp_buf ) ; 
, fclose( stream ); 

} ' 

} 

else 

printf( "Error opening file%s\n", sndfi iedd[loop_count] ) ; 



/* Put data in to Send Buffer, */ 

inemset(send_buf ,0, slzeot (send_buf)) ; 
street (send_buf . temp__buf }; 
street (send_Dut, " " ); 
Dutferjength - strienisendjbuf j ; 

} /* end if ]oop_count != 0 */ 



/* IT looping more than once open the next tpipe 
/* and read it into the tpipe. 



if (( stream = fopenftpipefi 1 edd ["loop count], Vb") ) != NULL } 

f 

num - fread( temp_buf, sizeof( char ). NUM_BUFFER. stream ); 
if (num == NUM_BUFFER) i 
fclose( stream } : 

} 

else < 
if ( f error (stream) ) 

print f( "Error opening file %s\n\sndfi I edd [loop, count]) ; 
else if { feof (stream)) < 
printf { "EOF founa\n" ); 

pnntt( "Number of characters read %d\n", num ); 
onntf( "temp_buf = %,*s\n". temp_buf); 
rclose( stream ); 



printf( "Error opening fiie%s\n", sndfi I edd [loop, count] ) ; 
memcpy (tpipe, temp_buf, 8); 



/* Prm 


t announcement of send API. */ 


print. ( 


'-\n-\n- Iteration #%d Send API . - 




1oop_count+l); 


printf ( 


'Tpine Name = J 5.8s.\n", tpipej; 


printf { 


'Transaction = %,8s,\n". trans); 


print. ( 


'RACF UserlD = %.8s.\n", user .name) ; 


print' ( 


'RACF Group - %.8s.\n". user nri ) ; 




'Lterm - %.8s.\n", Iterm ); 


printf ( 


'Modname = %.8s.\n", modname ); 


printf { 


'UTMA Data - %.5Gs.\n". otma_data ): 


print. ( 


'Send but = %s.\n", send.buf); 


print. ( 


'Send but at %.8x.\n". &send_DuH; 




('■Buffer length = %d.\n", buffer length); 


printf 


("Waiting for ecb at %.8x. =%.8x. \n" , ecb. 
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*ecb_list[l]); 

ot!na_send_async ( 

Sanchor, 
&retrsn, 
&ecbI0, 

&tpipe, 

&user__prf , 
K\i.rr~, 
&modname, 
&otma_data, 

(unsigned char *) &send buf , 

&buffer_l ength, 
0, 

&error_message, 
&send_options) ; 

DFSYCWAT(ecbJist[l]); 

/* Print results of send API. * 
printf ( "OTMA_SEND_ASYNC done. 

"Ecb at %.8x.=%.8x.\n", 
retrsn.ret, 
retrsn.rsn[6] , 
retrsn.rsn[l] , 



■■ (in) anchor block 
(out) return status 
= (out) ecb address 



user tpipe name 
IMS trancode or ct 
RACF userid 
RACF group name 
logical terminal 

OTMA user data 



* (in) 
" (in) 



* (in) 

* (in) 

* (in) 



* (in) send buffer 

>■■ (in) size of send buffer 

* (in) send_segment_! i st 

* (out) IMS Error msg. 

" (in) send special option 

* WAIT on ecb 



• %.8x rsn --■ %.8x,%.8x,%.8x,S 



retrsn,rsn[2] , 
retrsn.rsn[3] 
ecb J ist[l], 
*ecbjist[l] 



/+ Save otma_s 



/* Error Processing for OTMA SEND ASYNC API. */ 
if (retrsn.ret !-■ 0) 



/* Error path Free allocated session */ 

prsntf ("-Error send_async API retrsn.ret=%d\n", retrsn.ret) ; 
pnntt( "Error message sss\n", errorjnessage ); 

if (( stream - fopen(infi iedd[loot)_count] ,"rb")) != NULL ) 

num = freadf compare buf, sizeof( char ). NUH BUFFER, stream ); 
if (num --- NUM_BUFFER) i /* fread success */ 

printf ( "Compare_but = %.80s,W, compare_buf ); 

printf ( "Error_buf « >d.80s. W , errorjnessage ); 

fc!ose( stream ) ; 

compare_resul t - memc( comparejbut, errorjnessage ); 
prmtt( "compare_result - *si \n " . comparejresu 1 t ) : 
"if (comparej-esul I != 6) 
return(compare_resu!t) ; /* Exit if NO COMPARE */ 

if ( rerror^stream) ) /* possibility .1 */ 

pnntt( "Error reading tile -ssW, inf l ledd| loop_count] ) ; 

else if ( feof (stream)) i /* possibility 2 */ 
printf ( "EOF found\n" ); 

printf ( "Number of characters read 'Sd\n", num ); 

printf^ "Receive comparejbur = %.*s\n". num, comparejbuf) ; 
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else 

printf( "Error opening file %s\n", i 
printf("-\n"); 

/* Sever IMS connection 

printf(»-\n"); 
otma_close( 

& retrsn' /> 

); 

printf (''0TMA_CL0SE done, 
retrsn. ret, 

retrsn. rsn[l] , 
retrsn . rsn [21 , 
retrsn. rsn [3] 

); 



if i 1 edd [1 oop_count] } ; 



■ (in, out) tr to otma anchor */ 
; (out) rc, reason (1-4) */ 



%.8x rsn - %„8x,%.8x,%.8x,%.8 



] 



/* Initialize otmajrecei ve_async parameters. 
splat( rec J term , "" ); 
splat( recjnodname , 
splat{ rec_otma_data 
ecblO = 0; 

ecb_list[l] (unsigned long *) 
((unsigned long)&(ecbI0) j 



' ); 



* clear ecb for reuse 

* posted by OTMA 



ng) 0x80080080) ; /* end of list 
*/ 



/'* Print announcement of receive API. 
printf ("-\n-\n- Iteration #%d Receiv< 

loop_count+l); 
printf ("Tpipe Name = %.8s.\n", tpipe); 
printf ("Waiting for ecb at %.8x-%.8x. \n" , ecb_!ist[l], 

*ecb_list[l]); 

otma_receive_async( 



&anchor, 


/* (in) anchor block 




/* (out) return status 


SecblO,' 


/* (out) ecb address 




/* (in) user tpipe name 


J i or-, 


/•* (in) logical terminal 




/* (in) module name 


&rec~otnia_data. 


/* (in) OTMA user data 


&rec buf, 


/* (out) Receive buffer 


&rec_hufferjen. 


/* (in) size of rec buffer 


&rec data len, 


/* (in) send_segment__l i st 


0, 


/* (in/out) rec multiple seg 


&rec_options); 





DFSYCWAT (ecb_l i s t [1 ] ) ; 

/* Print results of receive API. 
printf ("OTMA REC ASYNC c 
"Ecb at %.8x.-%.l 



retrs 



.ret, 



).rsn[0] 
retrsn. rsn [1] 
retrsn. rsn [2] 
retrsn. rsn [3] 
ecbJistiT], 
*ecb list [ID 
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printf '("Lterm = %.8s.\n", recjterm ); 
printf ("Modname = %.8s.\n", rec_modname ); 
printf ("OTMA Data - %.50s.\n", rec_otma_data ): 
printf("Receive buf - %.8Qs.\n", rec_buf ) ; 
printf ("Receive buf at %,8x,\n", &rec_buf) ; 
printf ("Data length = %d.\n", rec_data_l en) ; 
printf ("Buffer length = %d.\n", rec_buffer_len) ; 



;_async Return Code. */ 



/* Error Processing for 0TMA_REC E I V E_AS Y NC API, 
if (retrsn. ret != 0} 



/* Error path Free allocated session 

pri ntf ("-error path retrsn . ret=%d\n" , retrsn . ret") ; 



■ntf("-\n"); 
ia_close( 



' (out) rc, reason (1-4) */ 



printf ("GTMAJ 

retrsn. 
retrsn. 
retrsn. 
retrsn. 



LOSE done, ret = %.8x r 

rsn[0], 
rsnfl] , 
rsn[2L 



S . 8x , % .8x,%.8x,%. 8x\n" , 



return (retsave) ; 



5 API return code 



/* Open the compare file containing the expected output 

/* of the receive buffer. Compare the expected output 
/* with the actual output and return the result. 



printf("-\n-\n- Iteration #%d Data Validation \n-\n", 

1 oop__count+l) : 

if (( stream = fopen(infiledd[loop_count] ,"rb")) !--■ NULL ) 

num - fread( compare_buf , sizeof( char ), NUM_BUFFER, stream ); 
if (num — NUM_BUFFER) { /* fread success */ 

printf ( "compare_buf « %.80s.\n", compare_buf ); 

pri ntf ( " rec_buf = %.80s.\n", rec_buf ); 

fclosef stream ) ; 

coirtpare__resul t = memc( compare_buf , rec_buf ); 
printf ( "compare__result = %i\n",compare_result) ; 
if (compare_resu'lt; != 0) 
return (compare_resul t) ; /* Exit if NO COMPARE */ 

else { /* fread () failed */ 

if ( ferror(stream) ) /* possibility I */ 

printf( "Error reading file %s\n", infiledd[loop__count]); 
else if ( feof (stream)) { /* possibility 2 */ 

printf( "EOF found\n" j; 

printf ( "Number of characters read %d\n", num ); 

printf ( "Receive compare_buf - %.*s\n", num, compare_buf) ; 
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printf( "trror opening file %s\n ,! 
memset(rec_buf , ' ' , sizeof (rec_bi 



printf( "End of loop \n" ); 
/* end of loop */ 



printf ("-\n") ; 



/* Finally, CLOSE severs the connection v, 

/* Storage used by the OTMA API. 

/* This will be done at job-step terminat 



printf("OTMA_CLOSE 
retrsn 



[0], 
[1], 
[2] . 

[3] 



/'* (in, out) ptr to otma ant 
/* (out) rc, reason (1-4) 



i « %.8x,%.8x,%.8x,%.8x \n", 



Subroutine to compare expected results (coiiipare_buf) */ 
with actual results(err_msg) the "|" is used to signify */ 
an ignore comoare and "V" is used to mark the end of string. */ 
Compare starts using an index i=l le. the 2nd character */ 
because the 1st character was blanked out. ( NL x'15' ) */ 
+/ 



[ (.j (0} 8& (comp__buf [i; 



if( comp_buf[T| 
if( comp_buf[i 



= rec_bufl|T 



/* Ignore compare */ 
/* compare ok ? */ 



printf( "MISCGMPARE !!! 
printf ( l! comp__buf [%d] = ; 
printf ( Vec_buf 1 [%d] = ' 



::oi"p bufTi] ) ; 
rec bufl[i] ); 
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Notices 



This information was developed for products and services offered in the U.S.A. IBM 
may not offer the products, services, or features discussed in this document in other 
countries. Consult your local IBM representative for information on the products and 
services currently available in your area. Any reference to an IBM product, program, 
or service is not intended to state or imply that only that IBM product, program, or 
service may be used. Any functionally equivalent product, program, or service thai 
does not infringe any IBM intellectual property right may be used instead. However, 
it is the user's responsibility to evaluate and verify the operation of any non-IBM 
product, program, or service. 

IBM may have patents or pending patent applications covering subject matter 
described in this document. The furnishing of this document does not give you any 
license to these patents. You can send license inquiries, in writing, to: 

IBM Director of Licensing 
IBM Corporation 
North Castle Drive 
Armonk. NY 10504-1785 
U.S.A. 

For license inquiries regarding double-byte (DBCS) information, contact the IBM 
Intellectual Property Department in your country or send inquiries, in writing, to: 

IBM World Trade Asia Corporation 
Licensing 

2-31 Roppongi 3-chome, Minato-ku 
Tokyo 106, Japan 

The following paragraph does not apply to the United Kingdom or arsy other 
country where such provisions are irseorssisterst with focal law: 
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS 
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS 
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A 
PARTICULAR PURPOSE. Some states do not allow disclaimer of express or 
implied warranties in certain transactions, therefore, this statement may not apply to 
you. 

This information could include technical inaccuracies or typographical errors. 
Changes are periodically made to the information herein; these changes will be 
incorporated in new editions of the publication. IBM may make improvements and/or 
changes in the product(s) and/or the program(s) described in this publication at any 
time without notice. 

Any references in this information to non-IBM Web sites are provided for 
convenience only and do not in any manner serve as an endorsement of those 
Web sites. The materials at those Web sites are not part of the materials for this 
IBM product and use of those Web sites is at your own risk. 

IBM may use or distribute any of the information you supply in any way it believes 
appropriate without incurring any obligation to you. 

Licensees of this program who wish to have information about it for the purpose of 
enabling: (i) the exchange of information between independently created programs 
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and other programs (including this one) and (ii) the mutual use of the information 
which has been exchanged, should contact: 

IBM Corporation 
J46A/G4 

555 Bailey Avenue 

San Jose', CA 95141-1003 

U.S.A. 

Such information may be available, subject to appropriate terms and conditions, 
including in some cases, payment of a fee. 

The licensed program described in this information and all licensed material 
available for it are provided by IBM under terms of the IBM Customer Agreement, 
IBM international Program License Agreement, or any equivalent agreement 
between us. 

Any performance data contained herein was determined in a controlled 
environment. Therefore, the results obtained in other operating environments may 
vary significantly. Some measurements may have been made on development-level 
systems and there is no guarantee that these measurements will be the same on 
generally available systems. Furthermore, some measurement may have been 
estimated through extrapolation. Actual results may vary. Users of this document 
should verify the applicable data for their specific environment. 

Information concerning non-IBM products was obtained from the suppliers of those 
products, their published announcements or other publicly available sources. IBM 
has not tested those products and cannot confirm the accuracy of performance, 
compatibility or any other claims related to non-IBM products. Questions on the 
capabilities of non-IBM products should be addressed to the suppliers of those 
products. 

Ail statements regarding IBM's future direction or intent are subject to change or 
withdrawal without notice, and represent goals and objectives only. 

This information is for planning purposes only. The information herein is subject to 
change before the products described become available. 

This information contains examples of data and reports used in daily business 
operations. To illustrate them as completely as possible, the examples include the 
names of individuals, companies, brands, and products. All of these names are 
fictitious and any similarity to the names and addresses used by an actual business 
enterprise is entirely coincidental. 

COPYRIGHT LICENSE: 

This information contains sample application programs in source language, which 
illustrates programming techniques on various operating platforms. You may copy, 
modify, and distribute these sample programs in any form without payment to IBM, 
for the purposes of developing, using, marketing or distributing application programs 
conforming to the application programming interface for the operating platform for 
which the sample programs are written. These examples have not been thoroughly 
tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, 
serviceability, or function of these programs. You may copy, modify, and distribute 
these sample programs in any form without payment to IBM for the purposes of 
developing, using, marketing, or distributing application programs conforming to 
IBM's application programming interfaces. 
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Each copy or any portion of these sample programs or any derivative work, must 
include a copyright notice as follows: 

© (your company name) (year). Portions of this code are derived from IBM Corp, 
Sample Programs. © Copyright IBM Corp. ___enter the year or years.,,. All rights 
reserved. 

If you are viewing this information softcopy, the photographs and color illustrations 
may not appear. 



Programming Interface Information 

This book is intended to help you use IMS Open Transaction Manager Access 
(OTMA) and can be used to write an OTMA client. This book documents 
General-use Programming Interface and Associated Guidance Information provided 
by IMS. 

General-use programming interfaces allow the customer to write programs that 
obtain the services of IMS. 

General-use Programming interface and Associated Guidance Information is 
identified where it occurs by an introductory statement to a section or topic. 



Trademarks 

The following terms are trademarks of International Business Machines Corporation 
in the United States, other countries, or both: 



BookManager MVS/ESA 

CICS " NetView 

DataPropagator OS/390 

DB2 ' QMF 

DB2 Universal Database RACF 

IBM Tivoli 

IMS VTAM 

IMS/ESA WebSphere 

MQSeries z/OS 
MVS 



Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in 
the United States, other countries, or both. 

UNIX is a registered trademark of The Open Group in the United States and other 
countries. 

Other company, product or service names may be trademarks or service marks of 
others. 
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